RestAPI 设计

最新推荐文章于 2024-08-16 16:42:20 发布

weixin_34138255

最新推荐文章于 2024-08-16 16:42:20 发布

阅读量74

点赞数

文章标签： python

原文链接：https://my.oschina.net/u/3035165/blog/912273

版权

2019独角兽企业重金招聘Python工程师标准>>>

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

转载于:https://my.oschina.net/u/3035165/blog/912273