RESTful API 接口开发规范

基本要求

RESTful API的基本要求如下：

1、协议：RESTful API应该使用HTTP/HTTPS协议进行通信。

2、请求方法：RESTful API常用的请求方法有GET、POST、PUT、DELETE等。

3、无状态：RESTful API应该是无状态的，即它不应该依赖于上一个请求的状态。

4、缓存：RESTful API应该支持缓存机制，以提高性能和可用性。

5、幂等性：RESTful API的设计应具有幂等性，即对于同一个请求，无论请求多少次，结果都是一样的。

6、可扩展性：RESTful API应该具有良好的可扩展性，以便支持未来的新功能和业务场景。

​​​​​​​设计原则

在开发RESTful API时，应遵循以下设计原则：

1、面向资源：将网络上的资源视为实体，每个资源都有一个唯一的标识符（URI），并通过该标识符进行访问。

2、客户端-服务器架构：RESTful API采用客户端-服务器架构，客户端发送请求给服务器，服务器接收请求并返回响应。

3、无状态：RESTful API的设计应无状态，即服务器不保存之前的状态信息，每个请求都应独立于其他请求。

4、缓存：为了提高性能和可用性，RESTful API应支持缓存机制，允许客户端将之前请求的响应缓存下来，并在后续请求中重复使用。

5、一致性：RESTful API的设计应遵循统一的标准和最佳实践，确保不同系统之间的一致性。

​​​​​​​设计规范

为了实现高质量、可读性、可维护性和可扩展性的RESTful API，应遵循以下设计规范：

1、资源路径设计：资源路径应清晰明了，能够唯一地标识每个资源。资源路径的层次结构应与现实世界的概念相对应。

1）接口路径以 /api 或 /[version]/api 开头

1. 正确：/api/task 或 /v2/api/tasks
2. 错误：/biz/tasks 或 /biz/api/tasks

2）接口路径以 api/aa-bb/cc-dd 方式命名

1. 正确：/api/task-groups
2. 错误：/api/taskGroups

3）接口路径使用资源名词而非动词

1. 正确：POST /api/tasks 或 /api/task-groups/1/tasks 
2. 错误：POST /api/create-task

4）接口路径中的资源使用复数而非单数

1. 正确：/api/tasks
2. 错误：/api/task

2、HTTP方法使用：根据不同的业务需求，选择合适的HTTP方法（GET、POST、PUT、DELETE等）来操作资源。对于不同的方法，应定义其语义和行为。

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

---POST（CREATE）：在服务器新建一个资源；

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

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

---DELETE（DELETE）：从服务器删除资源；

---HEAD：获取资源的元数据；

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

3、请求参数设计：请求参数应明确、简洁、易于理解和使用。参数的名称和类型应清晰地定义。参数的默认值应避免使用。

---?limit=20：指定返回记录的数量为20；

---?offset=8：指定返回记录的开始位置为8；

---?page=1&per_page=50：指定第1页，以及每页的记录数为50；

---?sortby=name&order=asc：指定返回结果按照name属性进行升序排序；

---?animal_type_id=2：指定筛选条件。

4、返回结果设计：返回结果应包含请求处理的结果和状态信息。返回结果的数据结构应清晰、易于理解和使用。

1）服务器会向用户返回的常用状态码和提示信息：

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

---201 CREATED - [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]：用户请求的格式不可得；

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

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

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

2）针对不同操作，服务器向用户返回的结果应该符合以下规范：

---GET /collection：返回资源对象的列表（数组）；

---GET /collection/resource：返回单个资源对象；

---POST /collection：返回新生成的资源对象；

---PUT /collection/resource：返回完整的资源对象；

---PATCH /collection/resource：返回完整的资源对象；

---DELETE /collection/resource：返回一个空文档。

5、错误处理：在请求处理过程中出现错误时，API应返回适当的错误信息，以便客户端能够识别问题并采取适当的措施。

6、版本控制：为了确保API的稳定性和兼容性，API应进行版本控制，并为不同的版本定义不同的资源路径。

7、安全性：为了保护API的安全性，API应采用适当的安全措施，如身份验证、授权、防止恶意代码注入等。

8、可读性：API的文档应清晰明了，易于阅读和理解。文档应包括API的使用指南、请求参数定义、返回结果定义和错误信息定义等内容。

9、可维护性：API的设计应易于维护和扩展。当需求发生变化时，API应能够灵活地进行修改和扩展，以满足新的需求。

10、可扩展性：API的设计应具有良好的可扩展性，以便支持未来的新功能和业务场景。