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