restful api 规范那些事

前言

公司的项目是采用微服务架构来构建的，提供的服务接口都是restful风格。之前也学习过restful的相关概念和知识。但是之前公司的项目一直没有涉及到restful，所以对于restful的理解也就停留在概念上。对于restful风格的实际操作还是有些地方需要注意下的。restful api接口设计的规范性还是很有必要去学习下的。

何为restful风格

REST这个词全称是Representational State Transfer，翻译成中文大意为表现层状态传输。当一个软件架构符合REST原则，我们称之为restful架构。说了这么多，我们为什么要使用restful架构？使用restful架构有什么好处？因为按照restful架构可以充分的利用HTTP协议带给我们的各种功能，算是对HTTP协议使用的最佳实践，还有一点就是可以使软件架构设计更加清晰，可维护性更好。

restful api规范

URL 规范

1. 动词 + 宾语

restful的核心思想就是，客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如，GET /articles这个命令，GET是动词，/articles是宾语。动词通常就是五种 HTTP 方法，对应 CRUD 操作。

  • GET：读取（Read）
  • POST：新建（Create）
  • PUT：更新（Update）
  • PATCH：更新（Update），通常是部分更新
  • DELETE：删除（Delete）

2. 宾语必须是名词

宾语就是 API 的 URL，是 HTTP 动词作用的对象。它应该是名词，不能是动词。比如，/articles这个 URL 就是正确的，而下面的 URL 不是名词，所以都是错误的。

  • /getAllCars
  • /createNewCar
  • /deleteAllRedCars

3. 复数 URL

既然 URL 是名词，那么应该使用复数，还是单数？这没有统一的规定，但是常见的操作是读取一个集合，比如GET /articles（读取所有文章），这里明显应该是复数。为了统一起见，建议都使用复数 URL，比如GET /articles/2要好于GET /article/2。

4. 避免多级 URL

常见的情况是，资源需要多级分类，因此很容易写出多级的 URL，比如获取某个作者的某一类文章。

GET /authors/12/categories/2

这种 URL 不利于扩展，语义也不明确，往往要想一会，才能明白含义。更好的做法是，除了第一级，其他级别都用查询字符串表达。

GET /authors/12?categories=2

下面是另一个例子，查询已发布的文章。你可能会设计成下面的 URL。

GET /articles/published

查询字符串的写法明显更好。

GET /articles?published=true

5. 动词的覆盖

有些客户端只能使用GET和POST这两种方法。服务器必须接受POST模拟其他三个方法（PUT、PATCH、DELETE）。这时，客户端发出的 HTTP 请求，要加上X-HTTP-Method-Override属性，告诉服务器应该使用哪一个动词，覆盖POST方法。下面代码中，X-HTTP-Method-Override指定本次请求的方法是PUT，而不是POST。

POST /api/Person/4 HTTP/1.1  
X-HTTP-Method-Override: PUT

状态码规范

客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。HTTP 状态码就是一个三位数，分成五个类别。

这五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的（或者约定的）解释，客户端只需查看状态码，就可以判断出发生了什么情况，所以服务器应该返回尽可能精确的状态码。API 不需要1xx状态码，下面介绍其他四类状态码的精确含义。

当 API 发生错误时，必须 返回出错时的详细信息。目前常见返回错误信息的方法有两种：

1、将错误详细放入 HTTP 响应首部；

X-MYNAME-ERROR-CODE: 4001
X-MYNAME-ERROR-MESSAGE: Bad authentication token
X-MYNAME-ERROR-INFO: http://docs.example.com/api/v1/authentication

2、直接放入响应实体中；

HTTP/1.1 401 Unauthorized
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:02:59 GMT
Connection: keep-alive

{"error_code":40100,"message":"Unauthorized"}

 考虑到易读性和客户端的易处理性，我们 必须 把错误信息直接放到响应实体中，其中错误码（error_code）必须 和 HTTP 状态码对应，也方便错误码归类，如：

HTTP/1.1 403 Forbidden
Server: nginx/1.11.9
Content-Type: application/json
Transfer-Encoding: chunked
Cache-Control: no-cache, private
Date: Sun, 24 Jun 2018 10:19:27 GMT
Connection: keep-alive

{"error_code":403002,"message":"用户已禁用"}

下面详细列举了各种情况 API 的返回说明。

200 ok 状态码是最常见的 HTTP 状态码，在所有成功的 GET 请求中，必须返回此状态码。HTTP 响应实体部分 必须直接就是数据，不要做多余的包装。

201 Created 当服务器创建数据成功时，应该返回此状态码。常见的应用场景是使用 POST 提交用户信息。

202 Accepted  该状态码表示服务器已经接受到了来自客户端的请求，但还未开始处理。常用短信发送、邮件通知、模板消息推送等这类很耗时需要队列支持的场景中。

204 No Content 该状态码表示响应实体不包含任何数据，其中：

  1. 在使用 DELETE 方法删除资源 成功 时，必须 返回该状态码
  2. 使用 PUT、PATCH 方法更新数据 成功 时，也 应该 返回此状态码

400 Bad Request 由于明显的客户端错误（例如，请求语法格式错误、无效的请求、无效的签名等），服务器 应该 放弃该请求。

401 Unauthorized 该状态码表示当前请求需要身份认证，以下情况都 必须 返回该状态码。

  1. 未认证用户访问需要认证的 API
  2. access_token 无效/过期

403 Forbidden 该状态码可以简单的理解为没有权限访问该请求，服务器收到请求但拒绝提供服务。

404 Not Found 该状态码表示用户请求的资源不存在。

500 Internal Server Error 该状态码 必须 在服务器出错时抛出，对于所有的 500 错误，都 应该 提供完整的错误信息支持，也方便跟踪调试。

503 Service Unavailable 该状态码表示服务器暂时处理不可用状态，当服务器需要维护或第三方 API 请求超时/不可达时，都 应该 返回该状态码。

响应规范

  •  不要返回纯本文

API 返回的数据格式，不应该是纯文本，而应该是一个 JSON 对象，因为这样才能返回标准的结构化数据。所以，服务器回应的 HTTP 头的Content-Type属性要设为application/json。客户端请求时，也要明确告诉服务器，可以接受 JSON 格式，即请求的 HTTP 头的ACCEPT属性也要设成application/json。下面是一个例子。

GET /orders/2 HTTP/1.1 
Accept: application/json
  • 发生错误时，不要返回 200 状态码

有一种不恰当的做法是，即使发生错误，也返回200状态码，把错误信息放在数据体里面，就像下面这样。

HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "failure",
  "data": {
    "error": "Expected at least two items in list."
  }
}

上面代码中，解析数据体以后，才能得知操作失败。这种做法实际上取消了状态码，这是完全不可取的。正确的做法是，状态码反映发生的错误，具体的错误信息放在数据体里面返回。就像下面

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "Invalid payoad.",
  "detail": {
     "surname": "This field is required."
  }
}

参考文献 

1.https://github.com/godruoyi/restful-api-specification

2.http://www.ruanyifeng.com/blog/2011/09/restful.html

3.http://www.ruanyifeng.com/blog/2014/05/restful_api.html

4.https://zh.wikipedia.org/zh-hans/HTTP%E7%8A%B6%E6%80%81%E7%A0%81