RestAPI 设计

RESTful API 设计最佳实践

使用 restful api 作为 web api，需要注意的如下几点

参考 OpenStack 的 port api 设计

使用名词定义接口，且是名词复数

对于获取所有用户，应该使用
/users

不应该使用
/getAllUsers

使用子资源来表达资源间的关系，如下表示id24的用户拥有的车子
/users/24/cars

GET 方法和查询参数不能改变资源状态

如果要改变资源的状态，使用 PUT, POST 和 DELETE。

API 版本化

版本号使用简单的序号，并避免点符号，如2.5等。正确用法如下：

/blog/api/v1

使用 HATEOAS 约束

当服务器发生了变化时，客户端并不需要做出修改，因为资源的 URI 和其他信息都是动态发现的。

{
"id": 711,
"manufacturer": "bmw",
"model": "X5",
"seats": 5,
"drivers": [
{
"id": "23",
"name": "Stefan Jauker",
"links": [
{
"rel": "self",
"href": "/api/v1/drivers/23"
}
]
}
]
}

提供过滤、排序、字段选择、分页

过滤：
GET /cars?color=red
GET /cars?seats<=2

排序：
GET /cars?sort=-manufactorer,+model

字段选择:
GET /cars?fields=manufacturer,model,id,color

分页:
GET /cars?offset=10&limit=5