浅析RESTful风格的API

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

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

以上的概念大概是许多关于RESTful中都会出现的定义概念。那么什么是表述性状态转移呢？首先，之所以晦涩是因为前面主语被去掉了，全称是 Resource Representational State Transfer：通俗来讲就是：资源在网络中以某种表现形式进行状态转移。在查询很多资料后看到一句很精简的总结：

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设计风格，说完RESTful接下来该说说API了。

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

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

那么下面来具体说说如何形成良好的RESTful风格的API设计

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

• http://api.qc.com/v1/newsfeed: 获取某人的新鲜;
• http://api.qc.com/v1/friends: 获取某人关系列表;

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

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

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

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

4. 使用子资源表达关系
如果一个资源与另外一个资源有关系，使用子资源：

5.使用Http头声明序列化格式
在客户端和服务端，双方都要知道通讯的格式，格式在HTTP-Header中指定
Content-Type 定义请求格式
Accept 定义系列可接受的响应格式

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

7.为集合提供过滤 排序 选择和分页等功能
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规定:

Link: https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5; rel=”next”,
https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3; rel=”last”,
https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5; rel=”first”,
https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5; rel=”prev”,

8.版本化你的API
也就是进行版本控制。无论你在设计什么系统，也不管你事先做了多么详尽的计划，随着时间的推移和业务的发展，你的程序总会发生变化，数据关系也会发生变化，资源可能会被添加或者删除一些属性。只要软件还在生存期内并且还有人在用它，开发人员就得面对这些问题，对于API设计来说，尤其如此。

在URL中加入版本号是一个优秀的API设计，当然还有另一个常用的解决办法就是把版本号放在请求首部中

使得API版本变得强制性，不要发布无版本的API，使用简单数字，避免小数点如2.5。一般在Url后面使用?v

/blog/api/v1

9. 使用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开发者应该避免这种错误。

1XX的返回码预留给HTTP的底层使用，在你的整个职业生涯中都不会主动发送这种返回码；

2XX的返回码表示请求按照预期执行并成功返回了信息。服务端要尽可能给用户返回这种结果。

3XX的返回码表示请求重定向，大多数API都不会经常使用这种请求（），但是最新的超媒体API会充分使用这些功能。

4XX的返回码主要表示由客户端引起的错误，例如请求参数错误或者访问一个不存在的资源，这些必须为幂等操作，并且不能改变服务器的状态（其实服务器的状态发生了改变就意味着操作不是幂等了）。

5XX的返回码主要表示由服务器引起的错误，通常情况下，这些错误都是开发人员

使用详细的错误包装错误：

{

  "errors": [

   {

    "userMessage": "Sorry, the requested resource does not exist",

    "internalMessage": "No car found in the database",

    "code": 34,

    "more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"

   }

  ]

}

10.允许覆盖http方法
一些代理只支持POST 和 GET方法， 为了使用这些有限方法支持RESTful API，需要一种办法覆盖http原来的方法。

使用订制的HTTP头 X-HTTP-Method-Override 来覆盖POST 方法.