资源定义

在RESTful架构设计中，系统的所有事物都被抽象为资源，这些资源通常对应服务器端领域模型中的实体类(Entity)。

URI规范

- 使用小写
- 单词间使用`-`，而不用`_`
- URI中使用名称表示资源并使用复数形式，如`users`
- 参数要encode

通信协议

所有的API访问总是通过https协议访问。

HTTP方法

操作资源必须尽可能使用正确的HTTP方法，并且遵守操作幂。以下是常用的HTTP方法：
幂等性：执行1次和多次的对资源产生的影响和返回的结果相同。

一旦定义好资源，需要确定什么样的action应用于它们并映射到API上。RESTful原则提供了使用Http方法处理对应CRUD操作的策略：
GET /users - 获取user列表
GET /users/1 - 获取一个user信息
POST /users - 新建一个user
PUT /users/1 - 更新user 1
DELETE /users/1 - 删除user 1

不符CRUD的操作

将操作动作看成子资源，通过PATCH或DELETE更新资源状态，例如Github的API中star和unstar一个项目可以这样表示：
star:

PUT /gists/:id/star

unstar:

DELETE /gists/:id/star

路径

在RESTful架构中，每个网址代表一种资源，以下是表示资源的两种方式：
资源集合：

https://api.lwhweb.com/users           //所有用户

https://api.lwhweb.com/users/1/books   //Id为1的用户的所有书籍

单个资源：

https://api.lwhweb.com/users/1         //Id为1的用户

复杂查询

过滤

常见的过滤条件是通过url参数实现，如https://api.lwhweb.com/users?name=lisi&age=13;参数的设计允许冗余，即允许API路径和URL参数偶尔有重复，如
GET /users/ID与GET /users?id=ID的含义是相同的。

排序

使用一个参数描述排序的字段，使用另一个参数描述排序方式(升序/降序)，例如：

?sortby=id&order=asc

分页

RESTful架构设计可以支持两种形式的分页。
一种是根据页码数(第几页)和每页查询多少条记录来查询，例如：

?page=2&pageSize=50

另一种则是从第几条数据开始，一共需要多少条记录来查询，例如：

?offset=10&limit=50

使用json返回数据

目前常用的两种数据格式是XML和json，但XML冗长，难以阅读，又不适合各种编程语言解析。当然XML有扩展性的优势，但是如果你只是将它来对内部资源串行化，那么他的扩展优势也发挥不出来。以下是Google上的趋势图，可见越来越多的应用使用json作为返回数据格式。

如果非得用XML返回数据，为了方便，应该在url中指定返回数据格式，避免修改http请求中的media和accept，例如：

GET https://api.lwhweb.com/users?format=xml    //要求返回XML格式数据
GET https://api.lwhweb.com/users?format=json   //要求返回JSON格式数据

错误处理

1、正确返回http状态码。API错误通常分两类：一是由客户端引发的诸如参数校验失败、权限校验失败等，二是由服务器引发的如代码逻辑错误、数据库连接失败、空指针异常等。对于第一类错误，应该正确返回相应的http状态码和错误描述，而第二类错误应该统一返回500状态码和错误信息，如“服务器出错，请联系管理员”。

2、返回的JSON错误尽可能包含错误码(可以在文档中查到更多信息)、错误信息以及可能的详细描述(非必需)，如：

{
  "code" : 1234,
  "message" : "Something bad happened",
  "description" : "More details about the error here"
}

3、对于PUT、PATCH、POST请求的验证错误信息应分解返回，最好是返回错误码和错误信息，并用error封装验证错误字段及错误信息，如：

{
  "code" : 1024,
  "message" : "Validation Failed",
  "errors" : [
    {
      "code" : 5432,
      "field" : "first_name",
      "message" : "First name cannot have fancy characters"
    },
    {
       "code" : 5622,
       "field" : "password",
       "message" : "Password cannot be blank"
    }
  ]
}

正确使用HTTP状态码

HTTP 响应代码可以保证客户端在第一时间用最高效的方式获知 API 运行结果，并采取相应动作。 以下是常用的HTTP状态码:

参考

Best Practices for Designing a Pragmatic RESTful API

GitHub API v3 | GitHub Developer Guide

Restful API 的设计规范

最佳实践：更好的设计你的 REST API