RESTful API 设计接口规范

• REST（Representational State Transfer）即表述性状态传递，REST指的是一组架构约束条件和原则。它是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。
• REST就是选择通过使用 http 协议和 uri，利用 client/ server model 对资源进行 CRUD (Create/Read/Update/Delete)增删改查操作。
• RESTful是一种网络应用程序的设计风格和开发方式，基于 HTTP，可以使用 XML 格式定义或 JSON 格式定义。可以通过一套统一的接口为 Web，iOS和Android提供服务

为什么需要Restful ？

1. URL具有很强可读性的，具有自描述性
2. 规范化请求过程和返回结果
3. 资源描述与视图的松耦合
4. 可提供OpenAPI，便于第三方系统集成，提高互操作性
5. 提供无状态的服务接口，降低复杂度，可提高应用的水平扩展性

Restful 的特点

1. 每一个URI代表1种资源；
2. 客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源；
3. 通过操作资源的表现形式来操作资源；
4. 资源的表现形式是XML或者HTML；
5. 客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。

Restful 的优点 

1. 面向资源，一目了然，具有自解释性。
2. 轻量，直接基于http，不再需要任何别的比如消息协议。get/post/put/delete为CRUD操作
3. 简单、低耦合
4. 数据描述简单，一般以xml，json做数据交换。服务器返回的数据格式，应该尽量使用JSON，避免使用XML。
5. 无状态，提高可见性（可以单独考虑每个请求），可靠性（更容易从局部故障中修复），可扩展性（降低了服务器资源使用）

在接口规范方面，我们遵循 Restful  规范，合理的利用 `请求方法`、`状态码` 等来设计 `API`，参考如下：

资源路径 URL

如果当前应用没有把接口数据与静态资源（如图片等）进行分开放置，为了进行区分

接口以 /api 作为前缀，静态资源以 /public 作为前缀。

为了更方便的对接口进行管理以及后续的升级，路径后同时携带当前接口的版本，如：/api/v1/signin

URL具体设计的规范如下：

1. 不用大写字母，所有单词使用英文且小写
2. 连字符用中杠"-“来提高URI的可读性，而不用下杠”_"
3. 正确使用 "/"表示层级关系，URL的层级不要过深，并且越靠前的层级应该相对越稳定
4. 结尾不要包含正斜杠分隔符"/"
5. URL中不出现动词，用请求方式表示动作
6. 资源表示用复数不要用单数
7. 不要使用文件扩展名

HTTP动词

对于资源的具体操作类型，由HTTP动词表示（括号里是对应的SQL命令）。

1. GET（SELECT）：从服务器取出资源（一项或多项）。
2. POST（CREATE）：在服务器新建一个资源。
3. PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
4. PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
5. DELETE（DELETE）：从服务器删除资源。

过滤信息（Filtering）

如果记录数量很多，服务器不应该都将它们全部返回给用户。此时API应该提供参数，过滤返回结果，比如：

1. users?limit=10：指定返回记录的数量
2. users?offset=10：指定返回记录的开始位置。
3. users?pageNum=2&pageSize=100：指定第几页，以及每页的记录数。
4. users?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
5. users?animal_type_id=1：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /Info/ID/users与 GET /users?Info_id=ID 的含义是相同的。

状态码（Status Codes）

服务器向用户返回的状态码和提示信息，比如（方括号中是该状态码对应的HTTP动词）：

1. 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
2. 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
3. 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
4. 204 NO CONTENT - [DELETE]：用户删除数据成功。
5. 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
6. 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
7. 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
8. 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
9. 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
10. 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
11. 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
12. 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

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