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。