原文出处： waylau

Web API 近几年变得越来越火，而简捷的 API 设计在多后端系统交互应用中也变得尤为重要。凡是，会利用 RESTful API 来作为我们的 Web API 。本文先容了几种简捷 RESTful API 设计的最佳实践。

利用的名词而不是动词

利用名词来界说接口

HTTP 请求要领在RESTful Web 处事中的典范应用

资源	GET	PUT	POST	DELETE
一组资源的URI，劳务派遣管理系统，好比http://www.waylau.com/resources/	列出 URI，以及该资源组中每个资源的具体信息（后者可选）。	利用给定的一组资源替换当前整组资源。	在本组资源中建设/追加一个新的资源。 该操纵往来回回新资源的URL。	删除 整组资源。
单个资源的URI，好比http://www.waylau.com/resources/142	获取 指定的资源的具体信息，名目可以自选一个符合的网络媒体范例（好比：XML、JSON等）	替换/建设 指定的资源。并将其追加到相应的资源组中。	把指定的资源当做一个资源组，并在其下建设/追加一个新的元素，使其附属于当前资源。	删除 指定的元素。

不该该利用动词：

/getAllResources
/createNewResource
/deleteAllResources

GET 要领和查询参数不能改变资源状态

假如要改变资源的状态，利用 PUT, POST 和 DELETE。下面是错误的用 GET 要领来修改 user 的状态：

GET /users/711?activate 或
GET /users/711/activate

利用名词复数

不要夹杂名词的单复数。保持简朴，只用复数名词界说所有资源。

/cars 取代 /car
/users 取代 /user
/products 取代 /product
/settings 取代 /setting

利用子资源来表达资源间的干系

GET /cars/711/drivers/  返回 711 号 car 的所有 driver 列表
GET /cars/711/drivers/4 返回 711 号 car 的 4 号 driver

利用 HTTP header 来序列化名目

客户端、处事端都需要知道相互之间的通讯名目。这些名目可以界说在 HTTP header 内里：

Content-Type：界说了请求名目

Accept：界说了吸收相应的名目列表

利用 HATEOAS 约束

HATEOAS（Hypermedia as the engine of application state）是 REST 架构气势气魄中最巨大的约束，也是构建成熟 REST 处事的焦点。它的重要性在于冲破了客户端和处事器之间严格的契约，使得客户端可以越发智能和自适应，而 REST 处事自己的演化和更新也变得越发容易。 在先容 HATEOAS 之前，图纸加密，先先容一下 Richardson 提出的 REST 成熟度模子。该模子把 REST 处事凭据成熟度分别成 4 个条理：

第一个条理（Level 0）的 Web 处事只是利用 HTTP 作为传输方法，实际上只是长途要领挪用（RPC）的一种详细形式。SOAP 和 XML-RPC 都属于此类。

第二个条理（Level 1）的 Web 处事引入了资源的观念。每个资源有对应的标识符和表达。

第三个条理（Level 2）的 Web 处事利用差异的 HTTP 要领来举办差异的操纵，而且利用 HTTP 状态码来暗示差异的功效。如 HTTP GET 要领来获取资源，HTTP DELETE 要领来删除资源。

第四个条理（Level 3）的 Web 处事利用 HATEOAS。在资源的表达中包括了链接信息。客户端可以按照链接来发明可以执行的行动。

从上述 REST 成熟度模子中可以看到，利用 HATEOAS 的 REST 处事是成熟度最高的，也是推荐的做法。对付不利用 HATEOAS 的 REST 处事，客户端和处事器的实现之间是细密耦合的。客户端需要按照处事器提供的相关文档来相识所袒露的资源和对应的操纵。当处事器产生了变革时，如修改了资源的 URI，客户端也需要举办相应的修改。而利用 HATEOAS 的 REST 处事中，客户端可以通过处事器提供的资源的表达来智能地发明可以执行的操纵。当处事器产生了变革时，软件开发，客户端并不需要做出修改，因为资源的 URI 和其他信息都是动态发明的。

下面是一个 HATEOAS 的例子：

{
  "id": 711,
  "manufacturer": "bmw",
  "model": "X5",
  "seats": 5,
  "drivers": [
   {
    "id": "23",
    "name": "Stefan Jauker",
    "links": [
     {
     "rel": "self",
     "href": "/api/v1/drivers/23"
    }
   ]
  }
 ]
}

提供过滤、排序、字段选择、分页

过滤：

GET /cars?color=red 
GET /cars?seats<=2

排序：

GET /cars?sort=-manufactorer,+model

字段选择:

GET /cars?fields=manufacturer,model,id,color

分页:

GET /cars?offset=10&limit=5

API 版本化