RESTful Api 设计风格
协议：API 与用户的通信协议，总是使用 HTTPS 协议
域名：应该尽量将 API 部署在专用域名之下，如果确定 API 很简单，不会有进一步的扩展，可以考虑放在主域名之下。
版本：
应该将 API 的版本放在 URL 中：https://www.sunck.wang/api/v1.0
将版本号放在 HTTP 头信息中：https://www.sunck.wang/students
路径：表示 API 的具体网址，每个网址代表一种资源，所以网址中不能有动词，只能有名词，并且所用的名词往往与数据库的表名对应。数据库中的表示记录同种数据的集合，所以 API 中的名词也应该使用复数。
获取所有学生：
使用正确的 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': '该人已离职'
}
作者：rottengeek
原文链接：http://t.cn/RgC0MIP
第 19 期【Python自动化运维入门】正在火热招生中
第 8 期【Python自动化运维进阶】正在招生中
各位小伙伴们，详情请扫码咨询：
