restful风格的API

要说RESTful首先来说说REST – REpresentational State Transfer （表述性状态传递）

REST – REpresentational State Transfe

表述性状态转移是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是RESTful。需要注意的是，REST是设计风格而不是标准。

表属性状态转移

表属性状态转移，简单来说就是资源在网络中以某种表现形式进行状态转移。
用一句话来说就是：
使用URL定位资源，用HTTP动词（GET,POST,DELETE,PUT等）描述操作。
既然是用HTTP动词进行操作。那么需要了解这里列出的4.5个非常重要的HTTP动作，这里的0.5个是指PATCH，因为它在功能上与PUT非常类似，剩下4个通常被API开发人员两两结合使用

GET（SELECT）：从服务器获取一个指定资源或一个资源集合；
POST（CREATE）：在服务器上创建一个资源；
PUT（UPDATE）：更新服务器上的一个资源，需要提供整个资源；
PATCH（UPDATE）：更新服务器上的一个资源，只提供资源中改变的那部分属性；
DELETE（DELETE）：移除服务器上的一个资源；

还有两个不常见的HTTP动作：

HEAD – 获取一个资源的元数据，例如一组hash数据或者资源的最近一次更新时间；
OPTIONS – 获取当前用户（Consumer）对资源的访问权限；

restful风格的API

api

API是服务提供方和使用方之间的契约，打破该契约将会给服务端开发人员招来非常大的麻烦，这些麻烦来自于使用API的开发人员，因为对API的改动会导致他们的移动app无法工作。一个好的文档对于解决这些事情能起到事半功倍的作用，但是绝对多数程序员都不喜欢写文档。如果想让服务端的价值更好的体现出来，就要好好设计API。通过这些API，你的服务/核心程序将有可能成为其他项目所依赖的平台；你提供的API越易用，就会有越多人愿意使用它。规划API的展示形式可能比你想象的要简单，首先要确定你的数据是如何设计以及核心程序是如何工作的。

也就是说Server提供的RESTful API中，URL中只使用名词来指定资源，原则上不使用动词。“资源”是REST架构或者说整个网络处理的核心。

URL命名

Server提供的RESTful API中，URL中只使用名词来指定资源，原则上不使用动词。“资源”是REST架构或者说整个网络处理的核心。比如：

http://api.qc.com/v1/profile: 获取某人的详细信息;

URL是对资源描述的抽象，资源的描述一定是名词，如果引入了动词，那这个URL就表示了一个动作，而非一个资源，这样就偏离了REST的设计思想

版本化api

在 RESTful API 中，API 接口应该尽量兼容之前的版本。但是，在实际业务开发场景中，可能随着业务需求的不断迭代，现有的 API 接口无法支持旧版本的适配，此时如果强制升级服务端的 API 接口将导致客户端旧有功能出现故障。实际上，Web 端是部署在服务器，因此它可以很容易为了适配服务端的新的 API 接口进行版本升级，然而像 Android 端、IOS 端、PC 端等其他客户端是运行在用户的机器上，因此当前产品很难做到适配新的服务端的 API 接口，从而出现功能故障，这种情况下，用户必须升级产品到最新的版本才能正常使用。

为了解决这个版本不兼容问题，在设计 RESTful API 的一种实用的做法是使用版本号。一般情况下，我们会在 url 中保留版本号，并同时兼容多个版本。

Get方法和查询参数不应该涉及状态改变

使用PUT, POST 和DELETE 方法 而不是 GET 方法来改变状态，不要使用GET 进行状态改变:
通常，GET请求能够被浏览器缓存（而且通常都会这么做），例如，当用户发起第二次POST请求时，缓存的GET请求（依赖于缓存首部）能够加快用户的访问速度。一个HEAD请求基本上就是一个没有返回体的GET请求，因此也能被缓存。

使用复数名词

不要混淆名词单数和复数，为了保持简单，只对所有资源使用复数。

使用子资源表达关系

如果一个资源与另外一个资源有关系，使用子资源

使用Http头声明序列化格式

在客户端和服务端，双方都要知道通讯的格式，格式在HTTP-Header中指定
Content-Type 定义请求格式
Accept 定义系列可接受的响应格式

使用HATEOAS

Hypermedia as the Engine of Application State 超媒体作为应用状态的引擎，超文本链接可以建立更好的文本浏览

为集合提供过滤 排序 选择和分页等功能

Filtering过滤:
使用唯一的查询参数进行过滤：
GET /cars?color=red 返回红色的cars
GET /cars?seats<=2 返回小于两座位的cars集合
当用户请求获取一组对象列表时，你就需要对结果进行过滤并返回一组严格符合用户要求的对象。有时返回结果的数量可能非常大，但是你也不能随意对此进行约束，因为这种服务端的随意约束会造成第三方开发人员的困惑。如果用户请求了一个集合，并对返回结果进行遍历，然后只要前100个对象，那么这里就需要由用户来指明这个限制量。这样用户就不会有这样的疑惑：是他们程序的bug还是接口限制了100条？还是网络只允许传这么大的包？
Sorting排序:
允许针对多个字段排序
GET /cars?sort=-manufactorer,+model
这是返回根据生产者降序和模型升序排列的car集合
Field selection
移动端能够显示其中一些字段，它们其实不需要一个资源的所有字段，给API消费者一个选择字段的能力，这会降低网络流量，提高API可用性。
GET /cars?fields=manufacturer,model,id,color
Paging分页
使用 limit 和offset.实现分页，缺省limit=20 和offset=0；
GET /cars?offset=10&limit=5
为了将总数发给客户端，使用订制的HTTP头： X-Total-Count.
链接到下一页或上一页可以在HTTP头的link规定，遵循Link规定

使用Http状态码处理错误

API如果没有错误处理是很难的，只是返回500和出错堆栈不一定有用

Http状态码提供70个出错，我们只要使用10个左右：

200 – OK – 一切正常
201 – OK – 新的资源已经成功创建
204 – OK – 资源已经成功擅长
304 – Not Modified – 客户端使用缓存数据
400 – Bad Request – 请求无效，需要附加细节解释如 “JSON无效”
401 – Unauthorized – 请求需要用户验证
403 – Forbidden – 服务器已经理解了请求，但是拒绝服务或这种请求的访问是不允许的。
404 – Not found – 没有发现该资源
422 – Unprocessable Entity – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失。
500 – Internal Server Error – API开发者应该避免这种错误。

资源路径

RESTful API 的设计以资源为核心，每一个 URI 代表一种资源。因此，URI 不能包含动词，只能是名词。注意的是，形容词也是可以使用的，但是尽量少用。一般来说，不论资源是单个还是多个，API 的名词要以复数进行命名。此外，命名名词的时候，要使用小写、数字及下划线来区分多个单词。这样的设计是为了与 json 对象及属性的命名方案保持一致。

请求方式

可以通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。其中，GET 用于查询资源，POST 用于创建资源，PUT 用于更新服务端的资源的全部信息，PATCH 用于更新服务端的资源的部分信息，DELETE 用于删除服务端的资源。

【GET】 /users # 查询用户信息列表
【GET】 /users/1001 # 查看某个用户信息
【POST】 /users # 新建用户信息
【PUT】 /users/1001 # 更新用户信息(全部字段)
【PATCH】 /users/1001 # 更新用户信息(部分字段)
【DELETE】 /users/1001 # 删除用户信息

本文转自：

作者：赵客缦胡缨v吴钩霜雪明
链接：https://www.jianshu.com/p/a88d07ad1493
来源：简书