restful api的10个最佳实践

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方法。

 

"感情实在是场无法掌控的事,没有逻辑,没有规律,更没顺理成章的必然。"

上一篇:PHP 中创建数组的方法(私人收藏)


下一篇:吴裕雄--天生自然 JAVASCRIPT开发学习: Break 和 Continue 语句