落叶知秋|实战指南：10个有关RESTful API良好设计的最佳实践作者：JDON链接：WebAPI已经在最近几年

作者：JDON
链接：
Web API已经在最近几年变成重要的话题，一个干净的API设计对于后端系统是非常重要的。
通常我们为Web API使用RESTful设计， REST概念分离了API结构和逻辑资源，通过Http方法GET, DELETE, POST 和 PUT来操作资源。
下面是进行RESTful Web API十个最佳实践，能为你提供一个良好的API设计风格。
1.使用名词而不是动词
不要使用：
/getAllCars/createNewCar/deleteAllRedCars
2.Get方法和查询参数不应该涉及状态改变使用PUT, POST 和DELETE 方法而不是 GET 方法来改变状态，不要使用GET 进行状态改变:
GET /users/711?activateGET /users/711/activate
3.使用复数名词不要混淆名词单数和复数，为了保持简单，只对所有资源使用复数。
/cars 而不是 /car/users 而不是 /user/products 而不是 /product/settings 而部署 /setting
4. 使用子资源表达关系如果一个资源与另外一个资源有关系，使用子资源：
GET /cars/711/drivers/ 返回 car 711的所有司机GET /cars/711/drivers/4 返回 car 711的4号司机
5.使用Http头声明序列化格式在客户端和服务端，双方都要知道通讯的格式，格式在HTTP-Header中指定
Content-Type 定义请求格式Accept 定义系列可接受的响应格式
6.使用HATEOASHypermedia as the Engine of Application State 超媒体作为应用状态的引擎，超文本链接可以建立更好的文本浏览：
{
"id": 711,
"manufacturer": "bmw",
"model": "X5",
"seats": 5,
"drivers": [
{
"id": "23",
"name": "Stefan Jauker",
"links": [
{
"rel": "self",
"href": "/api/v1/drivers/23"
}
]
}
]
}
注意href指向下一个URL
7.为集合提供过滤排序选择和分页等功能Filtering过滤:
使用唯一的查询参数进行过滤：
GET /cars?color=red 返回红色的carsGET /cars?seats<=2 返回小于两座位的cars集合
Sorting排序:
允许针对多个字段排序
GET /cars?sort=-manufactorer,+model
这是返回根据生产者降序和模型升序排列的car集合
Field selection
移动端能够显示其中一些字段，它们其实不需要一个资源的所有字段，给API消费者一个选择字段的能力，这会降低网络流量，提高API可用性。
GET /cars?fields=manufacturer,model,id,color
Paging分页
使用 limit 和offset.实现分页，缺省limit=20 和offset=0；
GET /cars?offset=10limit=5>; rel="next",<;limit=3>; rel="last",<;limit=5>; rel="first",<;limit=5>; rel="prev",
8.版本化你的API使得API版本变得强制性，不要发布无版本的API ，使用简单数字，避免小数点如2.5.
一般在Url后面使用?v
/blog/api/v1
9. 使用Http状态码处理错误如果你的API没有错误处理是很难的，只是返回500和出错堆栈不一定有用
Http状态码提供70个出错，我们只要使用10个左右：
200 – OK – 一切正常201 – OK – 新的资源已经成功创建204 – OK – 资源已经成功擅长
【落叶知秋|实战指南：10个有关RESTful API良好设计的最佳实践】304 – Not Modified – 客户端使用缓存数据
400 – Bad Request – 请求无效，需要附加细节解释如 "JSON无效"401 – Unauthorized – 请求需要用户验证403 – Forbidden – 服务器已经理解了请求，但是拒绝服务或这种请求的访问是不允许的。 404 – Not found – 没有发现该资源422 – Unprocessable Entity – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失。