【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"
    }
  ]
}