RESTful风格的接口命名规范

公司突然要求使用接口地址使用RESTful风格的接口命名规范,于是周末就对restful接口命名规范做了一个总结

REST是一个术语的缩写,REpresentational State Transfer,中文直译是“表征状态转移”。
REST是一套风格约定,RESTful是它的形容词形式。比如一套实现了REST风格的接口,可以称之为RESTful接口。

REST 描述了 HTTP 层里客户端和服务器端的数据交互规则;客户端通过向服务器端发送 HTTP(s)请求,接收服务器的响应,完成一次 HTTP 交互。这个交互过程中,REST 架构约定两个重要方面就是HTTP请求的所采用方法,以及请求的链接。

因此,REST 规范可以简单粗暴抽象成以下两个规则:

  • 请求 API 的 URL 表示用来定位资源;
  • 请求的 METHOD 表示对这个资源进行的操作;

以下将以这两个规则为基础,描述如何构造一个符合 REST 规范的请求。

API的url

URL 用来定位资源,跟要进行的操作区分开,这就意味着URL不该有任何动词。

1.1 下面示例中的 get、create、search 等动词,都不应该出现在 REST 架构的后端接口路径中。比如:

/api/getUser
/api/createApp
/api/searchResult
/api/deleteAllUsers

1.2 当我们需要对单个用户进行操作时,根据操作的方式不同可能需要下面的这些接口:

/api/getUser (用来获取某个用户的信息,还需要以参数方式传入用户 id 信息)
/api/updateUser (用来更新用户信息)
/api/deleteUser (用来删除单个用户)
/api/resetUser (重置用户的信息)

1.3 可能在更新用户不同信息时,提供不同的接口,比如:

/api/updateUserName
/api/updateUserEmail
/api/updateUser

1.4 总结:

以上三种情况的弊端在于:首先加上了动词,肯定是使 URL 更长了;其次对一个资源实体进行不同的操作就是一个不同的 URL,造成 URL 过多难以管理。

其实当你回过头看“URL”这个术语的定义时,更能理解这一点。URL 的意思是统一资源定位符,这个术语已经清晰的表明,一个 URL 应该用来定位资源,而不应该掺入对操作行为的描述。

在 REST 架构的链接应该是这个样子:

一、请求 API 的 URL 表示用来定位资源

1、URL 中不应该出现任何表示操作的动词,链接只用于对应资源;

2、URL 中应该单复数区分,推荐的实践是永远只用复数;比如GET /api/users表示获取用户的列表;如果获取单个资源,传入 ID,比如/api/users/123表示获取单个用户的信息;(个人觉得还是要区分一下单复数,/api/users表示获取用户的列表;/api/user/123表示获取单个用户的信息。这样写的好处是通过地址就能得知返回的是实体是一个对象,还是一个集合)

3、按照资源的逻辑层级,对 URL 进行嵌套,比如一个用户属于某个团队,而这个团队也是众多团队之一;那么获取这个用户的接口可能是这样:GET /api/teams/123/members/234 表示获取 id 为 123 的小组下,id 为234 的成员信息。

按照类似的规则,可以写出如下的接口
/api/teams (对应团队列表)
/api/teams/123 (对应 ID 为 123 的团队)
/api/teams/123/members (对应 ID 为 123 的团队下的成员列表)
/api/teams/123/members/456 (对应 ID 为 123 的团队下 ID 未 456 的成员)

二、请求的 METHOD 表示对这个资源进行的操作

GET (SELECT):从服务器检索特定资源,或资源列表。
POST (CREATE):在服务器上创建一个新的资源。
PUT (UPDATE):更新服务器上的资源,提供整个资源。
PATCH (UPDATE):更新服务器上的资源,仅提供更改的属性。
DELETE (DELETE):从服务器删除资源。

 正确示例:

单资源( singular-resourceX )
url样例:order/ (order即指那个单独的资源X)
GET – 返回一个新的order
POST- 创建一个新的order,从post请求携带的内容获取值。

单资源带id(singular-resourceX/{id} )
URL样例:order/1 ( order即指那个单独的资源X )
GET – 返回id是1的order
DELETE – 删除id是1的order
PUT – 更新id是1的order,order的值从请求的内容体中获取。

复数资源(plural-resourceX/)
URL样例:orders/
GET – 返回所有orders

复数资源查找(plural-resourceX/search)
URL样例:orders/search?name=123
GET – 返回所有满足查询条件的order资源。(实例查询,无关联) – order名字等于123的。

 复数资源查找(plural-resourceX/searchByXXX)
URL样例:orders/searchByItems?name=ipad
GET – 将返回所有满足自定义查询的orders – 获取所有与items名字是ipad相关联的orders。

单数资源(singular-resourceX/{id}/pluralY)
URL样例:order/1/items/ (这里order即为资源X,items是复数资源Y)
GET – 将返回所有与order id 是1关联的items。

singular-resourceX/{id}/singular-resourceY/
URL样例:order/1/item/
GET – 返回一个瞬时的新的与order id是1关联的item实例。
POST – 创建一个与order id 是1关联的item实例。Item的值从post请求体中获取。

singular-resourceX/{id}/singular-resourceY/{id}/singular-resourceZ/
URL样例:order/1/item/2/package/
GET – 返回一个瞬时的新的与item2和order1关联的package实例。
POST – 创建一个新的与item 2和order1关联的package实例,package的值从post请求体中获得。

以上规范是以查询为主,下面重点说一下patch

patch主要用来更改部分字段,比如重命名,或者更改实体的状态。这个时候两个方法都要写,,不能都写成Patch /order/{id},这样区分不出来。这个时候可以这样做

/order/{id}/name (用来重命名)

/order/{id}/status(用来更改用户状态)

这样就可以通过url和 method的两种方式完美的区分开了两个方法。

此处特殊说明一下,有的博客中使用/order/name/{id}这样的命名规范,将id放在字段的后面,我不确定那种正确,但是根据查询的相关规则,我选择id还是直接跟在order后面合适。

 

上面的规则可以在继续递归下去,并且复数资源后面永远不会再跟随负数资源。
总结几个关键点,来更清晰的表述规则。

在使用复数资源的时候,返回的是最后一个复数资源使用的实例。
在使用单个资源的时候,返回的是最后一个但是资源使用的实例。
查询的时候,返回的是最后一个复数实体使用的实例(们)。

其他规范

一些其他规范:
规则1:URI结尾不应包含(/)
规则2:正斜杠分隔符(/)必须用来指示层级关系
规则3:应使用连字符( - )来提高URI的可读性
规则4:不得在URI中使用下划线(_)
规则5:URI路径中全都使用小写字母

 参考博客

https://blog.csdn.net/qq_35075909/article/details/91522242

https://www.cnblogs.com/alsf/p/9362264.html

 

posted @ 2020-01-05 20:45  快速突围  阅读(3718)  评论(0编辑  收藏