Django-RESTful Api 设计风格

协议

• API 与用户的通信协议总是使用 HTTPS 协议

域名

• 尽量将 API 部署在专用域名下：https://api.sunck.wang
• 如果 API 比较简单，不会有进一步的扩展，可以考虑放在主域名下：http://www.sunck.wang

版本

• 应该将 API 的版本放入 URL
• 将版本放到 HTTP 头信息

路径

• 表示 API 的具体网址
• 每一个网址代表一种资源，所以网址中不能有动词，只能是名词，而且所有的名词往往与数据库的表名对应。
• 获取所有的学生：
  • 错误路径：https://www.sunck.wang/getStudents
  • 正确路径：https://www.sunck.wang/students

使用正确的 HTTP 请求方法

• HTTP 请求方法 (SQL 命令)

  • GET(SELECT)：从服务器获取一个或多个资源
  • POST(CREATE)：在服务器新建一个资源
  • PUT(UPDATE)：在服务器更新资源，客户端提供改变后的完整资源
  • PATCH(UPDATE)：在服务器更新资源，客户端提供改变的属性
  • DELETE(DELETE)：从数据库删除资源
  • HEAD
  • OPTIONS

• 示例：

  • 列出所有学生：

    GET  https://www.sunck.wang/students

  • 获取某个指定编号的学生：

    GET  https://www.sunck.wang/students/ID

  • 获取某个指定编号班级的所有学生：

    GET  https://www.sunck.wang/grades/ID/students

  • 创建一个学生：

    POST  https://www.sunck.wang/students

  • 更新某个指定编号的学生信息 (提供该学生的所有信息)：

    PUT  https://www.sunck.wang/students/ID

  • 更新某个指定编号的学生信息 (提供该学生的部分信息)：

    PATCH  https://www.sunck.wang/students/ID

  • 删除某个指定编号的学生：

    DELETE  https://www.sunck.wang/students/ID

过滤信息

• 如果资源数据较多，服务器不能将所有的数据一次性全部返回给客户端。API 应该提供参数，过滤返回结果。

• 示例：

  • 指定返回记录的数量：

    GET  https://www.sunck.wang/students?limit=

  • 指定返回记录的开始位置：

    GET  https://www.sunck.wang/students?offset=

  • 指定返回第几页的数据，以及每页的记录数：

    GET  https://www.sunck.wang/students?page=&per_page=

  • 指定返回结果以哪个属性排序，以及排序方式

    GET  https://www.sunck.wang/students?sort=&order=

  • 指定筛选条件

    GET  https://www.sunck.wang/students?student_gt_age=20

    GET  https://www.sunck.wang/students?id=5

• 注意：参数的设计允许存在冗余，即允许 API 路径和 URL 参数偶尔有重复

  GET  https://www.sunck.wang/students/ID?id=20

状态码

• 作用：服务器向用户返回的状态和提示信息

  状态码 描述	请求	含义
  200 OK	GET	服务器成功返回用户请求的数据
  201 Created	POST、PUT、PATCH	用户新建或修改数据成功
  202 Accepted	*	表示请求已进入后台队列
  204 No Content	DELETE	用户删除数据成功
  400 Bad Request	POST、PUT、PATCH	用户发出的请求有错误
  401 Unauthorized	*	用户没有权限 (令牌、用户名、密码错误)
  403 Forbidden	*	表示用户得到授权 (与 401 相对)，但是访问是被禁止的
  404 Not Found	*	请求针对的是不存在的记录
  406 Not Acceptable	GET	用户请求的格式不可得 (比如用户请求 JSON 格式数据，但是只有 XML 格式)
  410 Gone	GET	用户请求的资源被永久删除，且不会再得到
  422 Unprocessable Entity	POST、PUT、PATCH	创建一个对象时，发生一个验证错误
  500 Internal Server Error		服务器发生错误

  * 表示任何请求都可以

错误处理

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

  {
      "error": 错误信息,
  }

响应结果

• 概述：针对不同的操作，服务器向用户反回的结果应该符合规范
• GET /students：返回资源对象的列表
• GET /students/ID：返回单个资源对象
• POST /students：返回新生成的完整的资源对象
• PUT /students/ID：返回新完整的资源对象
• PATCH /students/ID：返回新完整的资源对象
• DELETE /students/ID：返回一个空文档

使用链接关联相关的资源

• 概述：返回结果中提供了链接，链向了其他 API 方法，使用户不查阅文档，也知道下一步应该做什么

• 示例：

  [
      {
          "img":"http://www.sunck.wang/static/media/a.jpg"
          "detail":12343
          "name":"招商引资"
      },
  ]

  [
      {
          "link":{
              "rel":"collection http://www.sunck.wang",
              "href":"http://www.sunck.wang/static/media/a.jpg",
              "title":"lunbotu",
              "type":"image/png",
          },
          "detail":12343
          "name":"招商引资"
      },
  ]

• 键：

  • rel：表示这个 API 与当前网址的关系
  • href：表示 API 的路径
  • title：表示 API 的标题
  • type：表示返回类型