Restful API 设计参考原则

Posted 2020-10-08 努力奋斗的小墨鱼专栏

在项目中，需要为后台服务撰写API。刚开始接触的时候，并没有考虑太多，就想提供URL，服务端通过该URL进行查询、创建、更新等操作即可。但再对相关规范进行了解后，才发现，API的设计并没有那么简单，远远不是URL的问题，而是一个通信协议的整体架构

 

1. 使用GET、POST、PUT、DELETE这几种请求模式

请求模式也可以说是动作、数据传输方式，通常我们在web中的form有GET、POST两种，而在HTTP中，存在下发这几种。

GET (选择)：从服务器上获取一个具体的资源或者一个资源列表。 
POST （创建）： 在服务器上创建一个新的资源。
PUT（更新）：以整体的方式更新服务器上的一个资源。 
PATCH （更新）：只更新服务器上一个资源的一个属性。
DELETE（删除）：删除服务器上的一个资源。

 

2.使用名词而不是动词

Resource 资源	GET 读	POST 创建	PUT 修改	DELETE
/cars	返回 cars集合	创建新的资源	批量更新cars	删除所有cars
/cars/711	返回特定的car	该方法不允许(405)	更新一个指定的资源	擅长指定资源

不要使用：

/getAllCars
/createNewCar
/deleteAllRedCars

 

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

使用PUT, POST 和DELETE 方法 而不是 GET 方法来改变状态，不要使用GET 进行状态改变:

GET /users/711?activate 
GET /users/711/activate

 

4.使用复数名词

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

/cars 而不是 /car
/users 而不是 /user
/products 而不是 /product
/settings 而部署 /setting

 

5. 使用子资源表达关系

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

GET /cars/711/drivers/ 返回 car 711的所有司机
GET /cars/711/drivers/4 返回 car 711的4号司机

 

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

比如在数据过多, 需要对数据进行分页请求的时候, 我们应该统一 API 请求参数. 常见的有这些.

• limit=10 指定返回记录的数量
• offset=10 指定返回记录的开始位置。
• page=2&per_page=100 指定第几页，以及每页的记录数。
• sortby=name&order=asc 指定返回结果按照哪个属性排序，以及排序顺序。
• animal_type_id=1 指定筛选条件

Filtering过滤:

使用唯一的查询参数进行过滤：

GET /cars?color=red 返回红色的cars
GET /cars?seats<=2 返回小于两座位的cars集合

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",

 

7.版本化你的API

API的开发直接关系了APP是否可以正常使用，如果原本运行正常的API，突然改动，那么之前使用这个API的APP可能无法正常运行。APP是不可能强迫用户主动升级的，因此，通过API版本来解决这个问题。也就是说，API的多个版本是同时运行的，而且都要保证可以正常使用。

按照RESTful的规范，不同的版本也应该用相同的API URL，通过header信息来判断版本，再调用不同版本的程序进行处理。但是这明显会给开发带来巨大的成本。使得API版本变得强制性，不要发布无版本的API，使用简单数字，避免小数点如2.5.

解决办法有以下几种：

1.新版本兼容旧版本，所有旧版本的动作、字段、操作，都在新版本中可以被实现，但明显这样的维护成本很大；
2.不同的版本，用不同的URL来提供服务，在URL中通过v1、v2来区分版本号，比如v2.api.xxx.com/user的方式，或者http://api.domain.com/v2  或者http://www.domain.com/api/v2 。
3.每个接口有各自的版本，一般为接口添加个version的参数。

 

8.json数据类型

• Number：整数或浮点数
• String：字符串
• Boolean：true 或 false
• Array：数组包含在方括号[]中
• Object：对象包含在大括号{}中
• Null：空类型

所以，传输的数据类型不能超过这六种数据类型。以前，我们曾经试过传输Date类型，它会转为类似于"2016年1月7日 09时17分42秒 GMT+08:00"这样的字符串，这在转换时会产生问题，不同的解析库解析方式可能不同，有的可能会转乱，有的可能直接异常了。要避免出错，必须做特殊处理，自己手动去做解析。为了根除这种问题，最好的解决方案是用毫秒数或者字符串表示日期。

 

返回的数据结构

{
    code：0,
    message: "success",
    data: { key1: value1, key2: value2, ... }
}

• code: 返回码，0表示成功，非0表示各种不同的错误
• message: 描述信息，成功时为"success"，错误时则是错误信息
• data: 成功时返回的数据，类型为对象或数组

 

data字段只在请求成功时才会有数据返回的。数据类型限定为对象或数组，当请求需要的数据为单个对象时则传回对象，当请求需要的数据是列表时，则为某个对象的数组。这里需要注意的就是，不要将data传入字符串或数字，即使请求需要的数据只有一个，比如token，那返回的data应该为：

// 正确 data: { token: abcdedf }

// 错误 data: abcdefg

9. 使用Http状态码处理错误

不同错误需要定义不同的返回码，属于客户端的错误和服务端的错误也要区分，比如1XX表示客户端的错误，2XX表示服务端的错误

如果你的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开发者应该避免这种错误。

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

{

  "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 方法.