RESTful API 设计规范

一. RESTful API设计规范概述

以前的web开发的前端与后端是融合在一起的，比如之前的PHP，JSP，ASP等等。近年来随着移动互联网的飞速发展，各种类型的Client端层出不穷，就需要通过一套统一的接口分别为Web，iOS和Android乃至桌面端提供服务。另外对于广大平台来说，比如Facebook platform，微博开放平台，微信公共平台等，它们不需要有显式的前端，只需要一套提供服务的接口，而RESTful 是目前最流行的API设计规范，它被用于Web数据接口的设计，并对数据资源进行描述。

要理解RESTful架构，最好的方法就是去理解Representational State Transfer这个词组，直译过来就是表现层状态转化，其实它省略了主语。表现层其实指的是资源的表现层，也可以理解为资源在网络中以某种表现形式进行状态转移。

• Resource：资源，即数据；
• Representational：某种表现形式，比如用JSON，XML，JPEG等；
• State Transfer：状态变化。通过HTTP动词实现；

理解一个具体的RESTful架构——面向资源的架构（Resource-Oriented Architecture，ROA）：

• 资源是由URI来指定。与互联网上一系列的资源互动，调用它的URI。
• 对资源的操作包括获取、创建、修改和删除资源，这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。
• 通过操作资源的表现形式来操作资源。具体表现形式，应该在HTTP请求的头信息中用Accept和Content-Type字段指定。
• 资源的表现形式则是XML或者HTML，取决于读者是机器还是人，是消费web服务的客户软件还是web浏览器。当然也可以是任何其他的格式。

二. URL设计

       1. 使用动词和宾语的词语组合

RESTful的核心思想就是，客户端发出的数据 + 操作指令都是“动词+宾语”的结构，比如GET /articles这个命令，GET是动词，/articles是宾语，动词通常就有5种HTTP请求方法，对应CRUD操作，根据 HTTP 规范，动词一律大写。

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

2. 词语组合中动词的指定

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

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

上面代码中，X-HTTP-Method-Override指定本次请求的方法是PUT，而不是POST。

3. 词语组合中宾语的词性要求

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

# /getAllCars
# /createNewCar
# /deleteAllRedCars

4. RESTful风格URL的宾语单复数

既然URL词语组合中的宾语是名词，那就会存单复数的区别，这没有统一的规定，但是常见的操作是读取一个集合，比如GET /articles（读取所有文章），这里明显应该是复数。为了统一起见，建议都使用复数 URL，比如GET /articles/2，这样指定集合中的某一个要好于GET /article/2。

5. 避免多级URL

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

# GET /authors/12/categories/2
或
# GET /articles/published

只看这条URL一些人其实是很难瞬间理解这条URL实际上是什么意思或者需要想一下才能够理解。其实更好的方式是除了第一级其他级别都用查询字符串表达。

# GET /authors/12?categories=2
或
# GET /articles?published=true

三. RESTful返回中不同的状态码且RESTful API的状态码要精确

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

# 1xx：相关信息，接收的请求正在处理。
# 2xx：操作成功，请求正常处理完毕。
# 3xx：重定向，需要进行附加操作已完成请求。
# 4xx：客户端错误，服务器无法处理客户端发送的请求。
# 5xx：服务器错误，服务器处理请求出错。

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

1. RESTful API的状态码类别为2XX

# GET: 200 OK
# POST: 201 create //POST返回201状态码，表示生成了新的资源；
# PUT: 200 OK
# PATCH: 200 OK
# DELETE: 204 No Content //DELETE返回204状态码，表示资源已经不存在。
// 204表示请求处理成功成功，但是并没有资源可返回。

//202 Accepted状态码表示服务器已经收到请求，但还未进行处理，会在未来再处理，通常用于异步操作。
HTTP/1.1 202 Accepted

{
  "task": {
    "href": "/api/company/job-management/jobs/2130040",
    "id": "2130040"
  }
}

//发生错误时，不要返回 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."
  }
}

        206：该状态码表示客户端进行范围请求，而服务器成功执行这部分的GET请求。响应报文中包含由Content-Range指定范围的实体内容。

        参考： HTTP状态码206 && http视频文件传输（http 206）

        断点续传：Http 206 文件断点续传下载原理 &&  Http 206 文件断点续传下载原理

2. RESTful API的状态码类别为3XX

        API 用不到301状态码（永久重定向 Moved Permanently）和302状态码（暂时重定向，307也是这个含义），因为它们可以由应用级别返回，浏览器会直接跳转，API 级别可以不考虑这两种情况。

        301: 永久重定向，该状态码表示请求的资源被分配给了新的URI，以后应该使用资源现在所指定的URI。换言之，已经将资源对应的URI保存为书签了，如果需要访问则应该按照Location首部字段提示的URI重新保存。

       302：临时重定向，该状态码表示请求的资源已经被重新分配新的URI，希望用户本次使用新的URI进行访问。

        302（Found）是资源临时性的转移，换言之，已经移动的资源对应的URI是可能还会被改变的。

        API 用到的3xx状态码，主要是303 See Other，该状态码同302 Found状态码有着相同的功能，但是303状态码明确表示客户端应当采用GET方式获取资源。

        比如：当使用POST方法访问CGI程序，其执行之后的处理结果是希望客户端能以GET方法重定向到另一个URL上去时，返回303状态码时最为理想的。使用302 Found状态码同样可以达到这种效果。（注意：在HTTP1.1版之前的浏览器是不能正确的理解303状态码，现在很多浏览器会将302响应视为303响应，并且在GET方式访问Location中规定的URI的时候，而无视原来使用的请求方法。）

        当301，302，303响应状态码返回时，几乎所有的浏览器都会把POST改为GET，并删除请求报文内的主体，之后请求会自动再次发送。且301，302标准是禁止将POST方法改成GET方法，但实际使用并非严格按照该规则去做的。

HTTP/1.1 303 See Other
Location: /api/orders/12345

        304（Not Modified）：该状态码表示客户端返送附带条件的请求（采用GET方法的请求报文中包含，If-Match，If-Modified-Since，If-None-Match，If-Range，If-Unmodified-Since中的任一首部）时，服务器端允许请求访问资源，但并未满足条件的情况。

        307（Temporary Redirect）: 临时重定向，该状态码同302 Found含义相同，302的标准是禁止POST变换成GET，而307则会遵照浏览器标准，不会从POST变成GET。但是，对于处理响应时的行为，每种浏览器有可能出现不同的情况。

3. RESTful API的状态码类别为4XX

4XX状态码是表示客户端的错误

# 400 Bad Request：//服务器不理解客户端的请求，未做任何处理。
# 401 Unauthorized：//用户未提供身份验证凭据，或者没有通过身份验证。
# 403 Forbidden：//用户通过了身份验证，但是不具有访问资源所需的权限。
# 404 Not Found：//所请求的资源不存在，或不可用。
# 405 Method Not Allowed：//用户已经通过身份验证，但是所用的HTTP方法不在他的权限之内。
# 410 Gone：//所请求的资源已从这个地址转移，不再可用。
# 415 Unsupported Media Type：//客户端要求的返回格式不支持。比如，API只能返回JSON格式，但是客户端要求返回XML格式。
# 422 Unprocessable Entity ：//客户端上传的附件无法处理，导致请求失败。
# 429 Too Many Requests：//客户端的请求次数超过限额。

        400 （Bad Request）：该状态码表示请求报文中存在语法错误。如：请求体不允许有大写字母的条件。当错误发生时，需要修改请求的内容后再次发送请求。

4. RESTful API的状态码类别为5XX

5xx状态码表示服务端错误。一般来说，API 不会向用户透露服务器的详细信息，所以只要两个状态码就够了。

500 Internal Server Error： //客户端请求有效，服务器处理时发生了意外。
503 Service Unavailable： //服务器无法处理请求，一般用于网站维护状态。

四. 服务器返回的数据格式

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

GET /orders/2 HTTP/1.1
Accept: application/json

五. 提供链接

API 的使用者未必知道，URL 是怎么设计的。一个解决方法就是，在回应中，给出相关链接，便于下一步操作。这样的话，用户只要记住一个 URL，就可以发现其他的 URL。

这种方法叫做 HATEOAS，HATEOAS是Hypertext As The Engine Of Application State的缩写。在 Richardson Maturity Model中, 它是REST的最高级形态

参考：https://www.cnblogs.com/kaixinyufeng/p/8283289.html

https://www.springcloud.cc/spring-data-rest-zhcn.html

举例来说，GitHub 的 API 都在 api.github.com 这个域名。访问它，就可以得到其他 URL。

{
  ...
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  ...
}

上面的回应中，挑一个 URL 访问，又可以得到别的 URL。对于用户来说，不需要记住 URL 设计，只要从 api.github.com 一步步查找就可以了。HATEOAS 的格式没有统一规定，上面例子中，GitHub 将它们与其他属性放在一起。更好的做法应该是，将相关链接与其他属性分开。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "In progress",
   "links": {[
    { "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
    { "rel":"edit", "method": "put", "href":"/api/status/12345" }
  ]}
}