02 REST Resource

架构之:REST中的资源定义

简介

我们知道REST架构中资源是非常重要的,REST的一切都是围绕资源来定义的,那么资源是什么,怎么命名资源和对其定义呢?一起来看看吧。

资源

资源是什么呢?资源是REST中信息的关键抽象。在REST中任何可以被命名的信息都可以被称为资源。比如:实体、对象、文档、图像、实体集合、服务等。

资源是和状态相关的,任何一个特定时间点的资源都有属于自己的资源状态。这些状态是由数据、描述数据的元数据和超媒体链接组成。

怎么理解这个超链接呢?这个超链接指向的是资源相关的URI。

资源的请求方法

定义好了资源,我们还需要定义资源的请求方法。

很多人认为,REST的资源请求方法是不是就是 HTTP GET/PUT/POST/DELETE ? 事实上Roy Fielding在论文中从未提起应该在哪种情况下使用哪种方法。他所强调的只是它应该是统一的接口。

只要是统一的方法即可。

很多人喜欢将 HTTP 与 REST 进行比较。 但是REST 和 HTTP 不一样。在 REST 架构风格中,数据和功能被视为资源,并使用统一资源标识符 (URI) 进行访问。通过使用一组简单的、定义良好的操作来处理资源。客户端和服务器通过使用标准化的接口和协议(通常是 HTTP)来交换资源。

资源是与表现形式进行分离的,以便可以以各种格式访问其内容,例如 HTML、XML、纯文本、PDF、JPEG、JSON 等。

只不过因为REST更多的被应用在web程序中,所以HTTP只能算是REST的一种实现方式。他们是不等同的。

REST资源命名规则

在REST中,资源就是一切,所以对资源进行良好的命名是非常有必要的。

在REST中,任何可以被命名的信息都可以被称为资源,资源可以是单体也可以是集合,比如students是一个集合,表示很多学生,而一个student表示的是一个学生的个体。

那么我们可以使用/students来表示学生的集合资源,然后用/students/{studentID}来表示特定的某个学生。

单个资源也可能包含子集合,比如一个student可能有很多个课程,我们用courses来表示,那么其对应的URI就是:/students/{studentID}/courses

REST API使用URI来进行资源的定位,所以这个URI需要直观并且容易使用。

资源命名最佳实践

接下来,我们会讲解一下REST中资源的命名最佳实践。

使用名词来定义资源

资源本身就是一个名词,所以我们需要尽可能的用名词来定义资源,对资源的操作可以通过不同的方法来表示。

像我们之前定义的学生相关的资源:

/students
/students/{studentID}
/students/{studentID}/courses

事实上基本上所有的资源都可以被分为4类,分别是文档、集合、存储和控制器(document, collection, store and controller),我们在定义资源的是,需要尽可能的将其归类,然后使用对应的命名规则。

  • 文档

文档是一个类似于单一的对象实例或数据库记录的概念。 在 REST 中,您可以将其视为资源集合中的单个资源。

文档通常用单数来表示:

/managed-devices/{device-id}
/users/{id}
/users/admin 
  • 集合

集合很好理解,就是服务器管理的资源目录,它里面可以包含很多个资源,客户端可能会希望向集合中插入新的资源,但是是否能够插入是由服务器端来控制的。

集合通常用复数来表示。

/managed-devices
/users
/users/{id}/accounts
  • 存储

存储是客户端管理的资源库,对于该资源库的增删改查是由API客户端根据不同的调用方式来决定的。

存储通常用复数来表示。

/users/{id}/playlists
  • 控制器

控制器表示的是一个过程。 控制器资源就像可执行函数,有参数和返回值,输入和输出。

控制器通常用动词来表示。

/users/{id}/cart/checkout
/users/{id}/playlist/play

使用一致的命名规则

使用一致的资源命名约定和 URI 格式,以最大限度地减少歧义和最大的可读性和可维护性。

我们可以归纳为下面几点:

  1. 使用/来表示资源的层级关系,如:

/managed-devices
  1. 不要在资源的最后加上/,如:

/managed-devices/
  1. 如果名称太长,可以加上(-) 提高可读性:

/managed-entities/{id}/install-script-location  
  1. 不要使用下划线,如果要用,请使用(-) 。

  2. 使用小写字母,增加可读性。

  3. 不要添加文件后缀,如managed-devices.xml 直接用managed-devices表示即可。

不要在资源名字中使用CURD

CRUD应该由请求资源的方法来区分,不要直接在资源命名上带上CURD。

比如我想获取students的信息,那么定义的资源是/students而不是/get-students。

使用下面的请求方式,表示是get请求即可:

HTTP GET /students

使用查询组件过滤URI集合

很多时候,您会遇到需要根据某些特定资源属性对资源进行排序、过滤或限制的集合的需求。在这种情况下,不要创建新的API,而是在资源集合 API 中启用排序、过滤和分页功能,并将输入参数作为查询参数传递。 例如:

/managed-devices?region=USA
/managed-devices?region=USA&brand=XYZ

总结

以上内容就是今天要讲的REST资源命名规则,后面我们会介绍一个REST架构的更加严格的限制规则HATEOAS。

最后更新于