Restful风格API

RESTful API设计原则与规范

路径(Endpoints)
路径表示API的具体网址URL。在RESTful架构中，每个URL代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与代表的对象名称对应。一般来说，某一同种记录的”集合”（collection），所以API中的名词也应该使用复数。

具体细则：

使用名词而不是动词。
举例来说，某个URL是/cards/show/1，其中show是动词，这个URL就设计错了，正确的写法应该是/cards/1，然后用GET方法表示show。
如果某些动作是HTTP动词表示不了的，你就应该把动作做成一种资源。比如网上汇款，从账户1向账户2汇款500元，
错误的URI是：POST /accounts/1/transfer/500/to/2。
正确的写法是把动词transfer改成名词transaction，资源不能是动词，但是可以是一种服务：POST /transaction?from=1&to=2&amount=500.00。

使用复数名词。不要混淆名词单数和复数，为了保持简单，只对所有资源使用复数。
举例：

/cars 而不是 /car
/users 而不是 /user
/products 而不是 /product
/settings 而不是 /setting

使用子资源表达关系。如果一个资源与另外一个资源有关系，使用子资源。
举例：

GET /cars/911/drivers/ 返回 car 911的所有司机
GET /cars/911/drivers/8 返回 car 911的8号司机

一旦定义好了要暴露的资源，你可以定义资源上允许的操作，以及这些操作和你的API的对应关系：
GET /tickets # 获取ticket列表GET /tickets/12 #
查看某个具体的ticketPOST /tickets #
新建一个ticketPUT /tickets/12 # 更新ticket 12.DELETE /tickets/12 #删除ticekt 12
这个endpoint的单数复数一个可以遵从的规则是：虽然看起来使用复数来描述某一个资源实例看起来别扭，但是统一所有的endpoint，使用复数使得你的URL更加规整。这让API使用者更加容易理解，对开发者来说也更容易实现。

永远使用SSL毫无例外，永远都要使用SSL。你的应用不知道要被谁，以及什么情况访问。有些是安全的，有些不是。使用SSL可以减少鉴权的成本：你只需要一个简单的令牌（token）就可以鉴权了，而不是每次让用户对每次请求签名。值得注意的是：不要让非SSL的url访问重定向到SSL的url

HTTP动词(HTTP Verbs)
对于资源的具体操作类型，由HTTP动词表示。常用的HTTP动词有下面五个：

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。

过滤信息（Filtering）
如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。为集合提供过滤、排序、选择和分页等功能。

下面是一些常见的参数：

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?pageNumber=2&perSize=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如：

GET /zoo/ID/animals
与
GET /animals?zoo_id=ID

的含义是相同的

注：
①移动端能够显示其中一些字段，它们其实不需要一个资源的所有字段，给API消费者一个选择字段的能力，这会降低网络流量，提高API可用性。

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

状态码（Status Codes）
服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）：

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - []：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - []：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - []：表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - []：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH]：当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

错误处理（Error handling）
如果状态码是4xx，就应该向用户返回出错信息。尽量使用详细的错误包装信息：

{
    “errors”: [{
        “userMessage”: “Sorry, the requested resource does not exist”,
        “internalMessage”: “No car found in the database”,
        “code”: 4xx,
        “more info”: “http://dev.example.com/api/v1/errors/12345"
    }]
}

返回结果（Response）
服务器返回的数据格式，应该尽量使用JSON，避免使用XML。针对不同操作，服务器向用户返回的结果应该符合以下规范：

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

使用HATEOAS的Hypermedia API
RESTful API最好使用Hypermedia as the Engine of Application State（超媒体作为应用状态的引擎），即返回结果中提供链接，连向其他API方法，超文本链接可以建立更好的文本浏览，使得用户不查文档，也知道下一步应该做什么。

比如，当用户向api.example.com的根目录发出请求，会得到这样一个文档。

{

“link”: {

    “rel”: “collection https://www.example.com/zoos",

    “href”: “https://api.example.com/zoos",

    “title”: “List of zoos”,

    “type”: “application/vnd.yourformat+json”

}

}

上面代码表示，文档中有一个link属性，用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系（collection关系，并给出该collection的网址），href表示API的路径，title表示API的标题，type表示返回类型。

认证（Authentication）
API的身份认证尽量使用OAuth 2.0框架。