# 概述
RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计。
核心是面向资源：对象的单个实例。 例如，一只动物。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。你可以用一个 URL（统一资源定位符）指向它，每种资源对应一个特定的 URL。要获取这个资源，访问它的 URL 就可以，因此 URL 就成了每一个资源的地址或独一无二的识别符。
主要有请求方式、状态码、URL 规范、传参规范
# 请求方式
GET （SELECT）：从服务器取出资源（一项或多项） | |
POST （CREATE）：在服务器新建一个资源 | |
PUT （UPDATE）：在服务器更新资源（客户端提供改变后的完整资源） | |
PATCH （UPDATE）：在服务器更新资源（客户端提供改变的属性） | |
DELETE（DELETE）：从服务器删除资源 |
- 还有两个不常用的
HEAD ：获取资源的元数据 | |
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的 |
# 状态码
- 以下是常见状态码
200：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。 | |
201：用户新建或修改数据成功。 | |
202：表示一个请求已经进入后台排队（异步任务） | |
204：用户删除数据成功。 | |
205：重置内容。服务器处理成功，用户端（例如：浏览器）应重置文档视图。可通过此返回码清除浏览器的表单域 | |
301：永久重定向，请求的资源已被永久的移动到新URL。 | |
302：临时重定向。 | |
400：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。 | |
401：表示用户没有权限（令牌、用户名、密码错误）。 | |
403：表示用户得到授权（与401错误相对），但是访问是被禁止的。 | |
404：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。 | |
406：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。 | |
410：用户请求的资源被永久删除，且不会再得到的。 | |
422：当创建一个对象时，发生一个验证错误。 | |
500：服务器发生错误，用户将无法判断发出的请求是否成功。 | |
501：服务器不支持请求的功能，无法完成请求 | |
502：错误的网关，该服务器在充当网关或代理的同时，从尝试访问该请求的上游服务器接收到无效响应。 |
# URL
URL 结尾不应该包含斜杠 “/”
正斜杠分隔符”/“必须用来指示层级关系
使用连字符”-“来提高 URL 的可读性，而不是使用下划线”_”
URL 路径中首选小写字母
URL 路径使用名词或复数
- 版本规范
- 应该将 API 的版本号放入 URL。
- 另一种做法是，将版本号放在 HTTP 头信息中，但不如放入 URL 方便和直观。
https://api.example.com/v1 |
- 路径视网络上任何东西都是资源，比如一个动物园
https://api.example.com/v1/zoos |
- 完成某种操作
https://api.example.com/v1/zoos GET ：列出所有动物园 | |
https://api.example.com/v1/zoos POST ：新建一个动物园 | |
https://api.example.com/v1/zoos/ID GET ：获取某个指定动物园的信息 | |
https://api.example.com/v1/zoos/ID PUT ：更新某个指定动物园的信息（提供该动物园的全部信息） | |
https://api.example.com/v1/zoos/ID PATCH ：更新某个指定动物园的信息（提供该动物园的部分信息） | |
https://api.example.com/v1/zoos/ID DELETE：删除某个动物园 | |
https://api.example.com/v1/zoos/ID/animals GET ：列出某个指定动物园的所有动物 |
# 传参规范 (过滤信息)
如果记录数量很多，服务器不可能都将它们返回给用户。API 应该提供参数，过滤返回结果。
参数的设计允许存在冗余，即允许 API 路径和 URL 参数偶尔有重复。比如，
GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
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：指定筛选条件 |
