如何优雅的设计RESTful API？这是我看过讲的最清晰的文章！

RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计。它的大原则容易把握，可是细节不容易作对。

本文总结 RESTful 的设计细节，介绍如何设计出易于理解和使用的 API。

1、URL 设计

1.1 动词 + 宾语

RESTful 的核心思想就是，客户端发出的数据操做指令都是"动词 + 宾语"的结构。

好比，GET /articles这个命令，GET是动词，/articles是宾语。动词一般就是五种 HTTP 方法，对应 CRUD 操做。

• GET：读取（Read）

• POST：新建（Create）

• PUT：更新（Update）

• PATCH：更新（Update），一般是部分更新

• DELETE：删除（Delete）

根据 HTTP 规范，动词一概大写。

1.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。

1.3 宾语必须是名词

宾语就是 API 的 URL，是 HTTP 动词做用的对象。它应该是名词，不能是动词。

好比，/articles这个 URL 就是正确的，而下面的 URL 不是名词，因此都是错误的。

• /getAllCars

• /createNewCar

• /deleteAllRedCars

1.4 复数 URL

既然 URL 是名词，那么应该使用复数，仍是单数？这没有统一的规定，可是常见的操做是读取一个集合。

好比GET /articles（读取全部文章），这里明显应该是复数。

为了统一块儿见，建议都使用复数 URL，好比GET /articles/2要好于GET /article/2。

1.5 避免多级 URL

常见的状况是，资源须要多级分类，所以很容易写出多级的 URL，好比获取某个做者的某一类文章。

GET /authors/12/categories/2复制代码

这种 URL 不利于扩展，语义也不明确，每每要想一会，才能明白含义。

更好的作法是，除了第一级，其余级别都用查询字符串表达。

GET /authors/12?categories=2复制代码

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

GET /articles/published复制代码

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

GET /articles?published=true
复制代码

2、状态码

2.1 状态码必须精确

客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。

HTTP 状态码就是一个三位数，分红五个类别。

• 1xx：相关信息

• 2xx：操做成功

• 3xx：重定向

• 4xx：客户端错误

• 5xx：服务器错误

这五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的状况。

每一种状态码都有标准的（或者约定的）解释，客户端只需查看状态码，就能够判断出发生了什么状况，因此服务器应该返回尽量精确的状态码。

API 不须要1xx状态码，下面介绍其余四类状态码的精确含义。

2.2 2xx 状态码

200状态码表示操做成功，可是不一样的方法能够返回更精确的状态码。

• GET: 200 OK

• POST: 201 Created

• PUT: 200 OK

• PATCH: 200 OK

• DELETE: 204 No Content

上面代码中，POST返回201状态码，表示生成了新的资源；DELETE返回204状态码，表示资源已经不存在。

此外，202 Accepted状态码表示服务器已经收到请求，但还未进行处理，会在将来再处理，一般用于异步操做。

下面是一个例子。

HTTP/1.1 202 Accepted

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

2.3 3xx 状态码

API 用不到301状态码（永久重定向）和302状态码（暂时重定向，307也是这个含义）

由于它们能够由应用级别返回，浏览器会直接跳转，API 级别能够不考虑这两种状况。

API 用到的3xx状态码，主要是303 See Other，表示参考另外一个 URL。

它与302和307的含义同样，也是"暂时重定向"，区别在于302和307用于GET请求，而303用于POST、PUT和DELETE请求。

收到303之后，浏览器不会自动跳转，而会让用户本身决定下一步怎么办。

下面是一个例子。

HTTP/1.1 303 See Other
Location: /api/orders/12345复制代码

2.4 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：客户端的请求次数超过限额。

2.5 5xx 状态码

5xx状态码表示服务端错误。通常来讲，API 不会向用户透露服务器的详细信息，因此只要两个状态码就够了。

• 500 Internal Server Error：客户端请求有效，服务器处理时发生了意外

• 503 Service Unavailable：服务器没法处理请求，通常用于网站维护状态

3、服务器回应

3.1 不要返回纯本文

API 返回的数据格式，不该该是纯文本，而应该是一个 JSON 对象，由于这样才能返回标准的结构化数据。

因此，服务器回应的 HTTP 头的Content-Type属性要设为application/json。

客户端请求时，也要明确告诉服务器，能够接受 JSON 格式，即请求的 HTTP 头的ACCEPT属性也要设成application/json。

下面是一个例子。

GET /orders/2 HTTP/1.1 
Accept: application/json
复制代码

3.2 发生错误时，不要返回 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."
  }
}
复制代码

3.3 提供连接

API 的使用者未必知道，URL 是怎么设计的。一个解决方法就是，在回应中，给出相关连接，便于下一步操做。

这样的话，用户只要记住一个 URL，就能够发现其余的 URL。这种方法叫作 HATEOAS。

举例来讲，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" }
  ]}
}复制代码

End

做者：阮一峰

来源：

http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html

本文版权归做者全部

长按下图二维码，即刻关注【狸猫技术窝】 

阿里、京东、美团、字节跳动 顶尖技术专家坐镇 

为IT人打造一个 “有温度” 的技术窝！