发布时间2019-06-12 07:52:10
16
0
0

概述

RESTful 风格的 API 设计是围绕 Web 资源展开的,在基于 HTTP 协议的 Web 服务中,我们通过 URL 来表示资源的位置,通过在 HTTP 报文首部中设置相应的首部字段来表示资源的类型,资源的位置+类型+实体数据合起来称作资源的表现层,客户端与服务端的交互过程中,对资源的请求和访问可能导致其表现层状态的转化,比如获取、新增、更新、删除等,而这些状态变化则是通过 HTTP 请求方法来实现。

  1. 围绕「资源」展开,且这些资源通过 URL 进行标识,比如 /articles 用于表示所有文章,/articles/15 用于表示 ID 为 15 的文章,至于资源名称用单数还是复数,没有统一规定,但通常我们使用复数,另外 URL 要尽可能简单,不要拖泥带水;
  2. 与资源的交互通过 HTTP 请求方法来实现,而不是将操作动作包含到 URL 中,比如 GET /articles/15 用于获取 ID 为 15 的文章,DELETE /articles/15 用于删除 ID 为 15 的文章;
  3. 接口的设计需要遵循无状态原则,不同的接口请求之间不要有持久化的 Session 认证,每个接口请求都需要自己独自去认证;
  4. 返回的响应状态码尽可能精准描述服务器处理结果,比如成功用 2XX 状态码,重定向用 3XX 状态码,资源不存在用 404,没有权限用 403,需要认证用 401,服务器错误用 5XX 状态码,并且对异常情况尽可能在响应实体中予以说明;
  5. 约定在客户端与服务器交互过程中以 JSON 格式传递数据,即资源的外在表现形式是 JSON。

HTTP 状态码

  • 200 OK - 对成功的 GET、PUT、PATCH 或 DELETE 操作进行响应。也可以被用在不创建新资源的 POST 操作上
  • 201 Created - 对创建新资源的 POST 操作进行响应。应该带着指向新资源地址的 Location 头
  • 202 Accepted - 服务器接受了请求,但是还未处理,响应中应该包含相应的指示信息,告诉客户端该去哪里查询关于本次请求的信息
  • 204 No Content - 对不会返回响应体的成功请求进行响应(比如 DELETE 请求)
  • 304 Not Modified - HTTP 缓存 header 生效的时候用
  • 400 Bad Request - 请求异常,比如请求中的 body 无法解析
  • 401 Unauthorized - 没有进行认证或者认证非法
  • 403 Forbidden - 服务器已经理解请求,但是拒绝执行它
  • 404 Not Found - 请求一个不存在的资源
  • 405 Method Not Allowed - 所请求的 HTTP 方法不允许当前认证用户访问
  • 410 Gone - 表示当前请求的资源不再可用。当调用老版本 API 的时候很有用
  • 415 Unsupported Media Type - 如果请求中的内容类型是错误的
  • 422 Unprocessable Entity - 用来表示校验错误
  • 429 Too Many Requests - 由于请求频次达到上限而被拒绝访问