9-django——restful设计风格

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 之序列化