Web API在过去的几年里非常盛行，因为它有着语法简单、规范化和轻量级的优点，因为得到广泛的推崇，很多过往的技术手段都慢慢转换为使用Web API来开发。而Web API通常使用的设计方式是RESTful（Representational State Transfer，表述性状态转移），它使用了典型的HTTP方法，诸如GET、POST、PUT和DELETE来对资源进行管理和交互。
这里列出设计RESTful API的10个最佳实践。
1.在API中使用名词，而不是动词。
在RESTful中，API描述的应该是资源，而不是动作，因此在API应使用名词去描述资源，而不是动词用动词去描述动作。
|
RESOURCE
|
GET:READ
|
POST:CREATE
|
PUT:UPDATE
|
DELTE:DELETE
|
|---|---|---|---|---|
|
/cars |
返回一个car的列表 |
创建一个新的car |
更新car的信息 |
删除所有的car |
|
/cars/yanggb |
返回指定的car |
Method not allowed(405) |
更新指定的car的信息 |
删除指定的car |
而不是使用动词，比如下面的API是不推荐的：
/getAllCars 获取所有车辆 /createNewCar 创建新的车辆 /deleteAllRedCars 删除所有红色的车辆
2.GET方法和查询参数不应该改变资源状态。
GET方法的API应该是幂等的，即不应该改变资源的状态，无论请求多少次，返回的结果都是一致的。
如果要改变资源的状态，应该使用POST、PUT和DELETE方法。
3.使用名词的复数形式。
不要混合使用名词的单数和复数形式，而应该为所有的资源从一开始就保持使用复数形式。
/cars 替代 /car /users 替代 /user /products 替代 /product /settings 替代 /setting
4.为关系使用子资源。
假如资源连接到其他资源，则应该使用子资源的形式来设计API。
GET /cars/711/drivers 返回711车的驱动器列表
GET /cars/711/drivers/4 返回711车的#4驱动
5.使用HTTP头决定序列化格式。
在客户端和服务端都需要知道使用什么格式来进行通信，这个格式应该在HTTP头中指定。
Content-Type：定义请求的格式。
Accept：定义允许的响应格式的列表。
6.使用HATEOAS。
HATEOAS（Hypermedia as the Engine of Application State）是REST架构风格中最复杂的约束，也是构建成熟REST服务的核心。它是一个指导原则，规定超文本链接应该被用于在API中创建更好的资源导航。
{ "id": 711, "manufacturer": "bmw", "model": "X5", "seats": 5, "drivers": [{ "id": "23", "name": "yanggb", "links": [{ "rel": "self", "href": "/api/v1/drivers/23" }] }] }
在上面的返回结果中，包含了超文本链接资源的信息。
7.为集合提供过滤、排序、字段选择和分页。
过滤：为所有字段或者查询语句提供独立的查询参数。
GET /cars?color=red 返回红色车的列表 GET /cars?seats<=2 返回两座车的列表
排序：允许跨越多字段的正序或者倒序排列。
GET /cars?sort=-manufactorer,+model 返回排序的车辆列表
字段选择：只列出需要的字段。一些情况下，只需要在列表中查询几个有标识意义的字段，并不需要从服务端把所有字段的值都请求出来，因此需要API支持选择查询字段的能力。这样也可以在一定程度上提高网络传输的性能与响应速度。
GET /cars?fields=manufacturer,model,id,color 返回需要的车辆信息字段的列表
分页：使用offset和limit来获取固定数量的资源结果，当其中一个参数没有出现时，应该提供各自的默认值，比如默认取第一页，或者默认取20条数据。
GET /cars?offset=10&limit=5 返回第10页的5条车辆记录列表 GET /cars?&limit=5 返回前5条车辆记录列表 GET /cars?&offset=5 返回第5页的车辆记录列表（默认单页数量）
8.版本化API。
确保强制实行API版本，并且不要发布一个没有版本的API。使用简单的序列数字，比如v1，避免使用2.5.0这样的形式（点分隔符）。
/blog/api/v1
9.使用HTTP状态码处理错误。
忽略错误处理的API是很难使用的，简单的返回500和调用堆栈是非常不友好的，同时这些错误信息在一定程度上来说也是无用的。
使用HTTP状态码
HTTP标准中提供了70多个状态来描述返回值，但是我们并不需要用到其中的全部，只需要了解其中一些比较常用的就可以了。
200 – OK – 一切正常 201 – OK – 新资源已经被创建 204 – OK – 资源删除成功 304 – 没有变化，客户端可以使用缓存数据 400 – Bad Request – 调用不合法，确切的错误应该在error payload中描述 401 – 未认证，调用需要用户通过认证 403 – 不允许的，服务端正常解析和请求，但是调用被回绝或者不被允许 404 – 未找到，指定的资源不存在 422 – 不可指定的请求体 – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失 500 – Internal Server Error – 标准服务端错误，API开发人员应该尽量避开这种错误
使用error payloads
所有的请求异常都应该被映射到error payloads中。
{ "errors": [{ "userMessage": "Sorry, the requested resource does not exist", "internalMessage": "No car found in the database", "code": 34, "more info":"http://www.yanggb.com/blog/api/v1/errors/12345" }] }
10.允许重写HTTP方法。
一些代理只支持GET和POST方法。为了在这种限制下使用RESTful API（GET/POST/PUT/DELETE），则API需要重写HTTP方法。
比如可以使用自定义的X-HTTP-Method-Override HTTP头来重写POST方法。
"感情实在是场无法掌控的事，没有逻辑，没有规律，更没顺理成章的必然。"
