文章标题

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 [*]: 服务器发生错误，用户将无法判断发出的请求是否成功。