标签：

1.通过请求类型区分CRUD 方法   操作  

场景

 
GET   读  

/cars

/cars/711

 
POST   创建   /cars  
PUT   修改  

/cars/711

/cars

 
PATCH   部分修改   /cars/711  
DELETE   删除   /cars/711  
2.资源采用名词，且使用复数

GET /tickets - 获取 tickets 列表
GET /tickets/12 - 获取一个单独的 ticket
POST /tickets - 创建一个新的 ticket
PUT /tickets/12 - 更新 ticket #12
PATCH /tickets/12 - 部分更新 ticket #12
DELETE /tickets/12 - 删除 ticket #12

3.Get方法和查询参数不应该涉及状态改变

不要使用GET 进行状态改变，

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

4.使用子资源表达关系

如果一个资源与另外一个资源有关系，使用子资源：

GET /tickets/12/messages - 获取ticket #12下的消息列表 GET /tickets/12/messages/5 - 获取ticket #12下的编号为5的消息 POST /tickets/12/messages - 为ticket #12创建一个新消息 PUT /tickets/12/messages/5 - 更新ticket #12下的编号为5的消息 PATCH /tickets/12/messages/5 - 部分更新ticket #12下的编号为5的消息 DELETE /tickets/12/messages/5 - 删除ticket #12下的编号为5的消息

5.使用Http头声明序列化格式

在客户端和服务端，双方都要知道通讯的格式，格式在HTTP-Header中指定

Content-Type 定义请求格式
Accept 定义系列可接受的响应格式

6.过滤，排序，搜索设计

最好是尽量保持基本资源URL的简洁性。 复杂结果过滤器、排序需求和高级搜索 (当限定在单一类型的资源时) ，都能够作为在基本URL之上的查询参数来轻松实现。下面让我们更详细的看一下:

1)过滤: 对每一个字段使用一个唯一查询参数，就可以实现过滤。 例如，当通过“/tickets”终端来请求一个票据列表时，你可能想要限定只要那些在售的票。这可以通过一个像

GET /tickets?state=open

这样的请求来实现。这里“state”是一个实现了过滤功能的查询参数。

2)排序: 跟过滤类似, 一个泛型参数排序可以被用来描述排序的规则. 为适应复杂排序需求，让排序参数采取逗号分隔的字段列表的形式，每一个字段前都可能有一个负号来表示按降序排序。我们看几个例子:

GET /tickets?sort=-priority - 获取票据列表，按优先级字段降序排序 GET /tickets?sort=-priority,created_at - 获取票据列表，按“priority”字段降序排序。在一个特定的优先级内，较早的票排在前面

3)搜索: 有时基本的过滤不能满足需求，这时你就需要全文检索的力量。或许你已经在使用 ElasticSearch 或者其它基于 Lucene 的搜索技术。当全文检索被用作获取某种特定资源的资源实例的机制时， 它可以被暴露在API中，作为资源终端的查询参数，我们叫它“q”。搜索类查询应当被直接交给搜索引擎，并且API的产出物应当具有同样的格式，以一个普通列表作为结果。
把这些组合在一起，我们可以创建以下一些查询:

GET /tickets?sort=-updated_at - 获取最近更新的票 GET /tickets?state=closed&sort=-updated_at - 获取最近更新并且状态为关闭的票。 GET /tickets?q=return&state=open&sort=-priority,created_at - 获取优先级最高、最先创建的、状态为开放的票，并且票上有 ‘return‘ 字样。

4)一般查询定义方式

为了使普通用户的API使用体验更加愉快， 考虑把条件集合包装进容易访问的RESTful 路径中。比如上面的，最近关闭的票的查询可以被包装成 

GET /tickets/recently_closed

5)限制查询返回字段

API的使用者并不总是需要一个资源的完整表示。选择返回字段的功能由来已久，它使得API使用者能够最小化网络阻塞，并加速他们对API的调用。
使用一个字段查询参数，它包含一个用逗号隔开的字段列表。例如，，下列请求获得的信息将刚刚足够展示一个在售票的有序列表:

GET /tickets?fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

6）Paging分页

使用 limit 和offset.实现分页，缺省limit=20 和offset=0；

GET /cars?offset=10&limit=5

为了将总数发给客户端，使用订制的HTTP头： X-Total-Count.

链接到下一页或上一页可以在HTTP头的link规定，遵循Link规定: