Django进阶篇 Rest framework (四)

RESTful API 设计指南：

• 过滤信息
• 状态码
• 错误处理
• 返回结果
• Hypermedia API

⑥ 过滤信息

如果记录的数量很多，服务器不可能都将它们返回给用户。API 应该提供参数，过滤返回结果。

下面是一些常见的参数：

# 指定返回记录的数量

https://api.example.com/v1/zoos?limit=10

# 指定返回记录的开始位置

https://api.example.com/v1/zoos?offset=10

# 指定第几页，以及每页的记录数

https://api.example.com/v1/zoos?page=2&per_page=100

# 指定返回结果，按照哪个属性排序，以及排序顺序

https://api.example.com/v1/zoos?sortby=name&order=asc

# 指定筛选条件

https://api.example.com/v1/zoos?animal_type_id=1

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

比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

⑦ 状态码

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的 HTTP 动词）。

• 服务器成功返回用户请求的数据，该操作是幂等的。

200 OK - [ GET ]

• 用户新建或修改数据成功。

201 CREATED - [ POST/PUT/PATCH ]

• 表示一个请求已经进入后台排队（异步任务）。

202 Accepted - [ * ]

• 用户删除数据成功。

204 NO CONTENT - [ DELETE ]

• 用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。

400 INVALID REQUEST - [ POST/PUT/PATCH ]

• 表示用户没有权限（令牌、用户名、密码错误）。

401 Unauthorized - [*]

• 表示用户得到权限（与401错误相对），但是访问是被禁止的。

403 Forbidden - [*]

• 用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。

404 NOT FOUND - [*]

• 用户请求的格式不可得（比如用户请求 JSON 格式，但是只有 XML 格式）。

406 Not Acceptable - [GET]

• 用户请求的资源被永久删除，且不会再得到。

410 Gone - [GET]

• 当创建一个对象时，发生一个验证错误。

422 Unprocessable entity - [ POST/PUT/PATCH ]

• 服务器发生错误，用户将无法判断发出的请求是否成功。

500 INTERNAL SERVER ERROR - [*]

⑧ 错误处理

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

{

error: "Invalid API key"

}

⑨ 返回结果

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

• 返回资源对象的列表（数组）。

GET /collection

• 返回单个资源对象。

GET /collection/resource

• 返回新生成的资源对象。

POST /collection

• 返回完整的资源对象。

PUT /collection/resource

• 返回完整的资源对象。

PATCH /collection/resource

• 返回一个空文档。

DELETE /collection/resource

⑩ Hypermedia API

RESTful API 最好做到 Hypermedia，即返回结果中提供链接，连向其它 API 方法，使用户不查文档，也知道下一步应该做什么。

比如，当用户向 api.example.com 的根目录发出请求，会得到这样一个文档。

{

“link”: {

"rel": "collection https://www.example.com/zoos",

"href": "https://api.example.com/zoos",

"title": "List of zoos",

"type": "application/vnd.yourformat+json"

}

}

上面的代码表示，文档中有一个 link 属性，用户读取这个属性就知道下一步该调用什么 API 了。rel 表示这个 API 与当前网址的关系（collection 关系，并给出该 collection 的网址），href 表示 API 的路径，title 表示 API 的标题，type 表示返回类型。