文章标题

RESTful API设计指南

网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......)
因此，必须有一种统一的机制，方便不同的前端设备与后端进行通信。这导致API构架的流行。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。

一、协议

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

二、域名

应该尽量将API部署在专用域名之下

三、版本(Versioning)

应该将API的版本号放入URL

四、路径(Endpoint)

路径又称”终点”(endpoint)，表示API的具体网址

在RESTful架构中，每个网址代表一种资源(resource),所以网址中不能有动词，只能有名词，而且所用的名词往往与数据表的表格名对应。一般来说，数据库中的表都是同种记录的”集合”(collection),所以API中的名词也应该使用复数。

举例来说，有个API提供动物园(zoo)的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

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: 获取信息，关于资源的哪些属性是客户端可以改变的。

六、过滤信息

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

下面是一些常见的参数

?limit=10：指定返回记录的数量

?offset=10：指定返回记录的开始位置。

?page=2&per_page=100：指定第几页，以及每页的记录数。

?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

?animal_type_id=1：指定筛选条件

七、状态码(Status Codes)

服务器向用户返回的状态码和提示信息。

200 OK [GET]: 服务器成功返回用户请求的数据

201 CREATE [POST/PUT/PATCH]: 用户新建或修改数据成功

202 Accepted [*]: 表示一个请求已经进入后台排队(异步任务)

204 NO CONTENT [DELETE]: 用户删除数据成功

400 INVALID REQUEST [POST/PUT/PATCH]: 用户发出的请求有错误，服务器没有进行新建或修改数据的操作。

401 Unauthorized [*]: 表示用户没有权限(令牌、用户名、密码错误)

403 Forbidden [*]: 表示用户得到授权(与401错误相对)，但是访问被禁止的。

404 NOT FOUND [*]: 用户发出的请求针对的是不存在的记录，服务器没有进行操作。

406 Not Acceptable [GET]: 用户请求的格式不可得(比如用户请求JSON格式，但是只有XML格式)。

410 Gone [GET]: 用户请求的资源被永久删除，且不会再得到的。

422 Unprocesable entity [POST/PUT/PATCH]: 当创建一个对象时，发生一个验证错误

500 INTERNAL SERVER ERROR [*]: 服务器发生错误，用户将无法判断发出的请求是否成功。