Django进阶篇 Rest framework (三)

RESTful API 设计指南：

• 协议
• 域名
• 版本
• 路径
• HTTP 动词
• 过滤信息
• 状态码
• 错误处理
• 返回结果
• Hypermedia API

① 协议

API 与用户的通信协议，总是使用 HTTPs 协议。

② 域名

<1> 应该尽量将 API 部署在专用域名下（这种情况会存在跨域问题）

https://api.example.com

<2> 如果确定 API 很简单，不会有进一步的扩展，可以考虑放在主域名下。

https://example.org/api

③ 版本

• 应该将 API 的版本号放入 URL。

https://api.example.com/v1/

• 另一种做法是，将版本号放在 HTTP 头信息中，但不如放在 URL 方便和直观。

https://api.example.com/?version=v1

④ 路径

路径又称“终点”（endpoint）,表示 API 的具体网站，网络上任何东西都是资源，均使用名词表示（可复数），在 RESTful 架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。数据库中的表都是同种记录的“集合”，所以 API 中的名称也应该使用复数。

https://api.example.com/v1/zoos

https://api.example.com/v1/animals

https://api.example.com/v1/employees

⑤ HTTP 动词

对于资源的具体操作类型，由 HTTP 动词表示。

• 常用的 HTTP 动词有下面五个（括号里是对应的 SQL 命令）；

GET( SELECT )：从服务器取出资源（一项或多项）；

POST( CREATE )：在服务器新建一个资源；

PUT( UPDATE )：在服务器更新资源（客户端提供改变后的完整资源）；

PATCH( UPDATE )：在服务器更新资源（客户端提供改变的属性）；

DELETE( DELETE )：从服务器删除资源。

• 还有两个不常用的 HTTP 动词：

HEAD：获取资源的元数据。

OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。