Restful 接口设计规范

一、资源与 URL

1. 使用名词表示资源

URL 应该以名词为主，用来表示具体的资源，而不是动词。例如，/users 表示用户资源集合，/users/{id} 表示单个用户资源。

2. 采用复数形式

一般来说，资源的 URL 应该使用复数形式，这样更符合 RESTful 的设计理念，也更直观。如 /orders 而不是 /order。

3. 避免层级过深

URL 的层级结构不宜过深，尽量保持简洁，以便于理解和使用。例如，/api/v1/orders/{orderId}/items 比 /api/v1/orders/{orderId}/related-items/item-list 更清晰。

4. 使用清晰的命名

URL 中的单词应该使用有意义的命名，遵循一定的命名规范，如使用驼峰命名法或下划线分隔单词，提高可读性。

二、HTTP 方法

GET：用于获取资源。例如，`GET /users` 获取所有用户，`GET /users/{id}` 获取单个用户。
POST：用于创建新资源。例如，`POST /users` 用于创建一个新用户，请求体中包含新用户的信息。
PUT：用于更新资源的全部属性。例如，`PUT /users/{id}` 更新指定 ID 的用户的所有信息，请求体中包含完整的用户数据。
PATCH：用于更新资源的部分属性。例如，`PATCH /users/{id}` 可以只更新用户的部分字段，如 `name` 或 `email`。
DELETE：用于删除资源。例如，`DELETE /users/{id}` 删除指定 ID 的用户。

三、状态码

1. 2xx 成功

200 OK：表示请求成功，通常用于 GET、PUT、PATCH 请求。
201 Created：表示资源创建成功，常用于 POST 请求。
204 No Content：表示请求成功，但没有返回内容，常用于 DELETE 请求或某些不需要返回数据的 PUT、PATCH 请求。

2. 4xx 客户端错误

400 Bad Request：表示客户端请求有误，如请求参数不合法、缺少必要参数等。
401 Unauthorized：表示用户未授权，需要提供有效的身份验证信息才能访问资源。
403 Forbidden：表示用户已认证，但没有权限访问资源。
404 Not Found：表示请求的资源不存在。

3. 5xx 服务器错误

500 Internal Server Error：表示服务器内部发生错误，通常是服务器端的代码或配置问题。
503 Service Unavailable：表示服务器暂时不可用，可能是由于服务器维护、过载等原因。

四、数据格式

1. 使用 JSON

推荐使用 JSON 格式作为数据交换的格式，因为它具有良好的可读性和兼容性，易于在不同的平台和语言之间进行解析和处理。

2. 定义清晰的结构

返回的数据应该有清晰的结构，包含必要的字段和信息。例如，对于用户资源，返回的 JSON 数据可能包含 id、name、email 等字段。

3. 错误信息格式

当发生错误时，返回的错误信息应该包含明确的错误码、错误消息和相关的上下文信息，以便于客户端进行处理和调试。例如：{"errorCode": "400", "errorMessage": "Invalid request parameters", "details": {"param1": "Required parameter is missing"}}。

五、其他规范

1. 幂等性

PUT、DELETE 等操作应该具有幂等性，即多次执行相同的操作应该得到相同的结果，不会对资源产生额外的副作用。

2. 版本控制

可以在 URL 中加入版本号，如 /api/v1/users，以便于对接口进行版本管理，在不破坏现有接口的情况下进行功能升级和修改。

3. 安全与认证

根据接口的需求，采取适当的安全措施，如使用 HTTPS 协议进行数据加密传输，采用身份验证和授权机制，确保只有授权的用户能够访问敏感资源。

4. 文档化

为接口编写详细的文档，包括接口的功能描述、请求和响应的格式、参数说明、状态码含义等，方便其他开发者使用和维护接口。