【django】RESTful API 设计指南

目录

一、协议

二、域名

三、版本（Versioning）

四、路径（Endpoint）

五、HTTP动词

5.1 CRUD操作：

5.2 其他动词：

六、过滤信息（Filtering）

七、状态码（Status Codes）

八、错误处理（Error Handling）

九、返回结果

十、Hypermedia API

十一、其他

总结

---

前言：RESTful API 是确保前后端通信高效、一致和可扩展的关键。以下是对您提供的RESTful API设计指南的优化和改造建议，以使其更加清晰、实用且符合现代最佳实践。

一、协议

• 使用HTTPS：API与用户的通信应始终使用HTTPS协议，以保证数据传输的安全性。
• 考虑HTTP/2：如果可能，建议使用HTTP/2，它提供了更好的性能和安全性。

二、域名

• 专用子域名：将API部署在专用子域名下，如https://api.example.com。
• 主域名下的路径：如果API非常简单且不会有进一步扩展，可以考虑放在主域名下，如https://example.org/api/。

三、版本（Versioning）

• URL中的版本号：将API的版本号放入URL中，如https://api.example.com/v1/。
• 头部信息中的版本号：另一种做法是将版本号放在HTTP头信息中，例如Accept: application/vnd.example.v1+json，但不如放入URL直观。

四、路径（Endpoint）

• 资源导向：每个URL代表一种资源，只使用名词且通常为复数形式。
• 避免动词：路径中不应包含动词，例如：

GET /zoos：列出所有动物园POST /zoos：新建一个动物园GET /zoos/{id}：获取某个指定动物园的信息PUT /zoos/{id}：更新某个指定动物园的信息（提供该动物园的全部信息）PATCH /zoos/{id}：更新某个指定动物园的信息（提供该动物园的部分信息）DELETE /zoos/{id}：删除某个动物园GET /zoos/{id}/animals：列出某个指定动物园的所有动物DELETE /zoos/{id}/animals/{animal_id}：删除某个指定动物园的指定动物

五、HTTP动词

5.1 CRUD操作：

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

5.2 其他动词：

• HEAD：获取资源的元数据。
• OPTIONS：获取关于资源的哪些属性是客户端可以改变的信息。

六、过滤信息（Filtering）

• 分页：?page=1&per_page=100：指定第几页以及每页的记录数。
• 排序：?sort=name&order=asc：指定返回结果按照哪个属性排序以及排序顺序。
• 筛选条件：?animal_type_id=1：指定筛选条件。
• 冗余允许：允许API路径和URL参数偶尔有重复，如GET /zoo/{id}/animals与GET /animals?zoo_id={id}。

七、状态码（Status Codes）

常见状态码：

• 200 OK：成功返回用户请求的数据。
• 201 Created：用户新建或修改数据成功。
• 202 Accepted：请求已进入后台排队（异步任务）。
• 204 No Content：用户删除数据成功。
• 400 Bad Request：用户发出的请求有错误。
• 401 Unauthorized：表示用户没有权限。
• 403 Forbidden：表示用户得到授权，但访问被禁止。
• 404 Not Found：请求的资源不存在。
• 406 Not Acceptable：用户请求的格式不可得。
• 410 Gone：请求的资源被永久删除。
• 422 Unprocessable Entity：创建对象时发生验证错误。
• 500 Internal Server Error：服务器发生错误。

八、错误处理（Error Handling）

错误响应：对于4xx和5xx状态码，应向用户返回详细的错误信息。
示例：

{"error": "Invalid API key"
}

九、返回结果

规范：

• GET /collection：返回资源对象的列表（数组）。
• GET /collection/resource：返回单个资源对象。
• POST /collection：返回新生成的资源对象。
• PUT /collection/resource：返回完整的资源对象。
• PATCH /collection/resource：返回完整的资源对象。
• DELETE /collection/resource：返回一个空文档。

十、Hypermedia API

HATEOAS：RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法。
示例：

{"links": [{"rel": "self","href": "https://api.example.com/zoos/1","title": "Zoo Details","type": "application/json"},{"rel": "animals","href": "https://api.example.com/zoos/1/animals","title": "List of Animals in Zoo","type": "application/json"}]
}

十一、其他

• 身份认证：推荐使用OAuth 2.0框架进行API的身份认证。
• 数据格式：尽量使用JSON格式，避免使用XML。
• CORS支持：确保API支持跨源资源共享（CORS），以便前端应用能够跨域访问API。
• 限流：实现限流机制，防止滥用API。
• 日志记录：记录API的访问日志，便于监控和调试。

总结

通过上述优化和改造，您的RESTful API设计将更加符合现代最佳实践，提高API的可用性、安全性和可维护性。希望这些建议对您有所帮助！如果有更具体的需求或问题，请随时告诉我。