9-django——restful设计风格

scq000 发布于2019-07-30 17:07 / 778人阅读

摘要：设计风格协议与用户的通信协议，总是使用协议域名应该尽量将部署在专用域名之下，如果确定很简单，不会有进一步的扩展，可以考虑放在主域名之下。数据库中的表示记录同种数据的集合，所以中的名词也应该使用复数。

RESTful Api设计风格

协议：API与用户的通信协议，总是使用HTTPS协议

域名：应该尽量将API部署在专用域名之下，如果确定API很简单，不会有进一步的扩展，可以考虑放在主域名之下。

版本：

应该将API的版本放在URL中：https://www.sunck.wang/api/v1.0

将版本号放在HTTP头信息中：https://www.sunck.wang/students

路径：表示API的具体网址，每个网址代表一种资源，所以网址中不能有动词，只能有名词，并且所用的名词往往与数据库的表名对应。数据库中的表示记录同种数据的集合，所以API中的名词也应该使用复数。

获取所有学生：

https://www.sunck.wang/api/v1... 错误写法

https://www.sunck.wang/api/v1... 正确写法

使用正确的HTTP请求方法

方式	解释
GET select	从服务器获取资源(一项或者多项)
POST create	在服务器新建一个资源
PUT update	在服务器更新资源(客户端提供改变后的完整资源)
PATCH update	在服务器更新资源(客户端提供改的属性)
DELETE delete	从服务器删除资源
HEAD	获取资源的元数据
OPTIONS	获取信息，关于资源的哪些属性是客户端可以改变的

例子

描述	方式
列出所有班级	GET /grades/
获取某个指定班级编号的信息	GET /grades/id
列出某个指定编号的班级的所有学生	GET /grades/id/students/
获取某个指定编号的学生信息	GET /students/id
创建一个学生	POST /students/
更新某个指定学生的信息(信息全部由客户端提供)	PUT /students/id
删除某个指定编号的学生	DELETE /students/id
删除某个指定班级的下的所有学生	DELETE /grades/id/students/

过滤信息

如果资源数较多，服务器不能将所有数据一次全部返回给客户端，API应该提供参数，过滤返回结果

例子

描述	方式
指定返回记录的数量	GET /students/?limit=
指定返回记录的开始位置	GET /students/?offset=
指定返回第几页数据，以及每页的记录数	GET /students/?page=&per_page=
指定返回结果按照哪个属性排序，以及排序的顺序	GET /students/?sortby=&order=
指定筛选条件	GET /students/?student_age_gt=

注意：参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复

状态码

服务器向客户端返回的状态码和提示信息

错误处理

如果错误码是4xx，就应该向用户返回错误信息，一般来说，返回的信息中将error作为键名，出错的信息作为键值即可

{
    error:"Invalid API KEY",
}

响应结果

针对不同的操作，服务器向用户返回结果应该符合规范

方式	描述
GET /students/	返回资源对象的列表
GET /students/id/	返回单个资源对象
POST /students/	返回新生成的资源对象
PUT /students/	返回完整的资源对象
PATCH /students/	返回完整的资源对象
DELETE /students/id/	返回一个空文档

使用链接相关的资源

返回结果中提供了链接，链向了其他的API方法，使得用户不查看文档，也知道下一步应该做什么

示例

{
    link:"www.sunck.wang/grades/"
}
{
    "link":{
        "rel":"collection www.sunck.wang/index/",
        "href":"www.sunck.wang/grades/",
        "title":"List of Grades",
        "type":"application/json",
    }
}

键

rel：表示这个API与当前网址的关系

href：表示API路径

title：表示API的标题

type：表示返回的类型

其他：服务器返回的数据尽量使用JSON格式，避免使用XML格式

API文档规范要求

一、写明该接口的功能是什么

二、请求的URL是什么

三、请求方式是什么（POST、GET、 DELETE、PUT、 PATCH等）

四、参数是什么，此处还需说明你的参数名、参数类型、是否必填、参数的简单解释

五、请求成功时的响应内容（实际开发中，要与前端同事沟通使用什么样的数据结构），并且对其中的字段做出说明（包括含义、数据类型，数据结构<字符串，数组，字典等>）

六、请求失败时的响应内容，并且对其中的字段做出说明（包括含义、数据类型，数据结构<字符串，数组，字典等>）包括多带带的对错误码的说明

七、请求样例（返回结果部分要包括成功的情况和失败的情况）

八、最好写上文档的编写人和编写时间（可不写）

Demo：

功能：获取某人的下属

URL：”people/api/v1/ subordinate”

请求参数说明：

参数名	类型	是否必填	备注
uid	int	是	用户的id

请求成功参数说明

参数名	类型	说明
code	Int	响应状态码1代表成功
msg	string	响应信息
data	数组	数组内是字典类型，详情见下表

data内的响应参数说明

参数名	类型	说明
uid	int	下属的用户ID
name	string	下属的用户名
position	string	下属的岗位

请求失败参数说明

参数名	类型	说明
code	Int	响应状态码非1值
msg	string	错误提示信息

code值说明

Code	说明
1	成功
2	该人已经离职
3	请求参数不完整
4	参数类型错误

样例：

请求参数 uid 1

# 请求成功样例
{    
    "code": 1,
    "msg": "ok",
    "data":[
        {
        "uid":2,
        "name": "Tom",
        "position": "教师"
        },
        {
        "uid":3,
        "name’: "Lucy",
        "position": "助教"
        }
    ]
}

# 请求失败样例
    {
        "data": 2,
        "msg": "该人已离职"
}

10-django——RESTful API 之序列化

GPU云服务器云服务器设计风格网站设计风格 md设计风格 REST

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/42023.html

详解REST架构风格

摘要：但是远远不仅是指的风格，它是一种网络应用的架构风格。参考用定位资源在架构风格中，用来指定一个资源。完整状态码列表如何设计在过去不使用架构风格的时候，如果我们要设计一个系统，会以操作为出发点，然后围绕它去建设其他需要的东西。引言作为Web开发者，你可能或多或少了解一些REST的知识，甚至已经非常习惯于它，以至于在正式地学习REST的时候，你可能心里会想：本来就是这样做的啊，不然还能怎...

ChanceWong 2019-06-24 18:00 评论0 收藏0
浅谈REST风格

摘要：废话不多讲，下面就说说风格到底是个神马东东。一个资源可能会随着需求的变化而经历一个资源创建修改查询删除等过程，风格正是基于协议运行的，协议又被称为无状态协议，所以资源的变化需要在服务端完成。现如今微服务如日中天，那么大家有没有想过各个微服务之间是怎么调用数据亦或是怎么交互的呢？当然方式有很多，但今天所说的REST风格被业界推荐为微服务之间交互的首选方式（小编还是非常喜欢这种方式的）。...

Darkgel 2019-08-16 16:13 评论0 收藏0
那些年，我们一起误解过的REST

摘要：通过增删查改，引起资源状态的改变，称为状态转移。用于获取资源的元信息。方法与方法类似，都可以查询资源的元信息放在的，但不会返回资源的表述。表示请求有问题，如参数错误等。表示当前请求的某前置条件不符合。网关错误，从上游服务器收到无效响应。欢迎大家前往腾讯云+社区，获取更多腾讯海量技术实践干货哦~ 本文由sammyshen 发表于云+社区专栏最近几年REST API越来越流行，特别是...

DesGemini 2019-08-19 11:07 评论0 收藏0
RESTful实践（具体应用）思考

摘要：其他交互一般会遵循一些数据结构协议或者状态值，比如不同的操作结果对应不同的状态值，且出错会返回指定的错误信息方便前端进行提示等。 RESTful这种架构已经具有很长的时间和历程了，但似乎最近restful这个词出现的频率特别高，目前不是很清楚是因为我自个儿现在是以restful风格写程序产生的孕妇效应，还是单页面程序开发的流行造成的。其实一开始我也是不想写这篇文章的，因为网络上与re...

myshell 2019-06-28 13:49 评论0 收藏0
基于ThinkPHP 的Api 设计

摘要：前言关于的设计目前比较流行的是风格的设计譬如阮一峰的这篇设计指南中的介绍也有很多支持风格的框架具体请自己谷歌之但是实际开发中很对公司采用的并不是支持风格的框架而且是在实际的开发过程中接口分为不同的版本实现接口管理按照官网教程搭建项目配置默认前言关于Api的设计目前比较流行的是 restful 风格的Api设计,譬如阮一峰的这篇RESTful API 设计指南中的介绍,PHP也有很多...

lijy91 2019-06-27 11:40 评论0 收藏0