RESTfulAPI设计原则与规范

RESTful API设计原则与规范

一、背景与基础概念 2

二、RESTful API应遵循的原则 3

1、协议(Protocol) 3

2、域名(ROOT URL) 3

3、版本(Versioning) 3

4、路径(Endpoints) 4

5、HTTP动词(HTTP Verbs) 5

6、过滤信息（Filtering） 6

7、状态码（Status Codes）7

8、错误处理（Error handling）8

9、返回结果（Response）8

10、使用HATEOAS的Hypermedia API 8

11、认证（Authentication）9

三、Swagger API标准9

REST，即Representational State Transfer的缩写。RESTful架构，是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便，基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制，所以正得到越来越多网站的采用。如果一个架构符合REST原则，就称它为RESTful架构。

本文即将描述的，即是创建RESTful架构的API所要遵循的原则与规范。

一、背景与基础概念

Web 应用程序最重要的REST 原则是，客户端和服务器之间的交互在请求之间是无状态的。从客户端到服务器的每个请求都必须包含理解请求所必需的信息。

•资源（resource）：网络上的一个实体或者说是一个具体信息，可以是一段文本、一张图片、一首歌曲、一种服务。

•统一资源定位符（URI，Universal Resource Identifier）：一个资源的识别符或者说是一个地址，通过URI你可以定位到特定的资源。要获取这个资源，需要访问它的URI，因此，URI就成了每一个资源的地址或独一无二的识别符。

•状态转换（State Transfer）: 所有资源都共享统一的接口，以便在客户端和服务器之间传输状态。客户端与服务器互动的过程，通常涉及到服务器端数据和状态的变化过程，比如文件被修改，访问数量增加等。

使用的是标准的HTTP 方法，Http标准中定义的最主要四个动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：-GET：用来获取资源

-POST：用来新建资源

-PUT：用来更新资源

-DELETE：用来删除资源

•Hypermedia 是应用程序状态的引擎，资源表示通过超链接互联。

二、RESTful API应遵循的原则

1、协议(Protocol)

API与用户的通信协议，尽量使用HTTPs协议。HTTPs协议的所有信息都是加密传播，第三方无法窃听，具有校验机制，一旦被篡改，通信双方会立刻发现，配备身份证书，防止身份被冒充。

2、域名(ROOT URL)

应该尽量将API部署在专用域名之下。

https://

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

https:///api/

3、版本(Versioning)

应该将API的版本号放入URL。

https:///v1/

另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。

注：需要注意版本规划，以便以后API的升级和维护。使得API版本变得强制性，不要发布无版本的API，使用简单数字，避免小数点如2.5。

4、路径(Endpoints)

路径表示API的具体网址URL。在RESTful架构中，每个URL代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与代表的对象名称对应。一般来说，某一同种记录的”集合”（collection），所以API中的名词也应该使用复数。

具体细则：

1、使用名词而不是动词。举例来说，某个URL是/cards/show/1，其中show是动词，这个URL就设计错了，正确的写法应该是/cards/1，然后用GET方法表示show。如果某些动作是HTTP动词表示不了的，你就应该把动作做成一种资源。比如网上汇款，从账户1向账户2汇款500元，错误的URI是：POST /accounts/1/transfer/500/to/2。正确的写法是把动词transfer改成名词transaction，资源不能是动词，但是可以是一种服务：POST /transaction?from=1&to=2&amount=500.00。

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

举例：

/cars 而不是/car

/users 而不是/user

/products 而不是/product

/settings 而不是 /setting

3、使用子资源表达关系。如果一个资源与另外一个资源有关系，使用子资源。

举例：

GET /cars/911/drivers/ 返回car 911的所有司机

GET /cars/911/drivers/8 返回car 911的8号司机

5、HTTP动词(HTTP Verbs)

对于资源的具体操作类型，由HTTP动词表示。常用的HTTP动词有下面五个：

•GET（SELECT）：从服务器取出资源（一项或多项）。

•POST（CREATE）：在服务器新建一个资源。

•PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

•PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。

•DELETE（DELETE）：从服务器删除资源。

还有两个不常用的HTTP动词。

•HEAD：获取资源的元数据。