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是不推荐的：

2.GET方法和查询参数不应该改变资源状态。

GET方法的API应该是幂等的，即不应该改变资源的状态，无论请求多少次，返回的结果都是一致的。

如果要改变资源的状态，应该使用POST、PUT和DELETE方法。

3.使用名词的复数形式。

不要混合使用名词的单数和复数形式，而应该为所有的资源从一开始就保持使用复数形式。

4.为关系使用子资源。

假如资源连接到其他资源，则应该使用子资源的形式来设计API。

5.使用HTTP头决定序列化格式。

在客户端和服务端都需要知道使用什么格式来进行通信，这个格式应该在HTTP头中指定。

Content-Type：定义请求的格式。

Accept：定义允许的响应格式的列表。

6.使用HATEOAS。

HATEOAS（Hypermedia as the Engine of Application State）是REST架构风格中最复杂的约束，也是构建成熟REST服务的核心。它是一个指导原则，规定超文本链接应该被用于在API中创建更好的资源导航。

在上面的返回结果中，包含了超文本链接资源的信息。

7.为集合提供过滤、排序、字段选择和分页。

过滤：为所有字段或者查询语句提供独立的查询参数。

排序：允许跨越多字段的正序或者倒序排列。

字段选择：只列出需要的字段。一些情况下，只需要在列表中查询几个有标识意义的字段，并不需要从服务端把所有字段的值都请求出来，因此需要API支持选择查询字段的能力。这样也可以在一定程度上提高网络传输的性能与响应速度。

分页：使用offset和limit来获取固定数量的资源结果，当其中一个参数没有出现时，应该提供各自的默认值，比如默认取第一页，或者默认取20条数据。

8.版本化API。

确保强制实行API版本，并且不要发布一个没有版本的API。使用简单的序列数字，比如v1，避免使用2.5.0这样的形式（点分隔符）。

9.使用HTTP状态码处理错误。

忽略错误处理的API是很难使用的，简单的返回500和调用堆栈是非常不友好的，同时这些错误信息在一定程度上来说也是无用的。

使用HTTP状态码

HTTP标准中提供了70多个状态来描述返回值，但是我们并不需要用到其中的全部，只需要了解其中一些比较常用的就可以了。

使用error payloads

所有的请求异常都应该被映射到error payloads中。

10.允许重写HTTP方法。

一些代理只支持GET和POST方法。为了在这种限制下使用RESTful API（GET/POST/PUT/DELETE），则API需要重写HTTP方法。

比如可以使用自定义的X-HTTP-Method-Override HTTP头来重写POST方法。

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

你要去做一个大人，不要回头，不要难过。