什么是REST资源？ - 幂简集成

1.什么是资源？

在REST中，主数据表示称为资源。拥有一致且强大的REST资源命名策略——从长远来看，这将证明是最好的设计决策之一。

REST中信息的关键抽象是一个资源。任何可以命名的信息都可以是资源：文档或图像、临时服务（例如“洛杉矶今天的天气”）、其他资源的集合、非虚拟对象（例如一个人）等。

换句话说，任何可能成为作者超文本引用目标的概念都必须符合资源的定义。

资源是对一组实体的概念映射，而不是与任何特定时间点的映射相对应的实体。—罗伊·菲尔丁的论文

1.1.单人和收集资源

资源可以是单人或集合。

例如，“customers”是集合资源，而“customer”是单例资源（在银行领域中）。

我们可以使用URI“/customers”来识别“customers”集合资源。我们可以使用URI“/customers/{customerId}”识别单个“customer”资源。

/customers			//is a collection resource



/customers/{id}		// is a singleton resource

1.2.收集和子收集资源

资源也可能包含子集合资源。

例如，可以使用URN“/customers/{customerId}/accounts”（在银行域中）识别特定“customer”的子收集资源“accounts”。

同样，子集合资源“accounts”中的单元资源“account”可以识别如下：“/customers/{customerId}/accounts/{accountId}”。

/customers						//is a collection resource



/customers/{id}/accounts		// is a sub-collection resource

1.3.URI

REST API使用统一资源标识符（URI）来寻址资源。REST API设计者应该创建URI，将REST API的资源模型传达给API的潜在客户端。当资源命名得当时，API是直观且易于使用的。如果做得不好，同样的API使用和理解可能具有挑战性。

统一接口的约束部分通过URI和HTTP动词的组合以及根据标准和惯例使用它们来解决。

以下是一些提示，让您在为新API创建资源URI时继续前进。

PauseNextUnmute

Current Time 1:24

Duration 1:45

Loaded: 99.94%SubtitlesFullscreen

2.最佳实践

2.1.使用名词来表示资源

RESTful URI应该引用一个事物（名词）的资源，而不是引用一个动作（动词），因为名词具有动词没有的属性——同样，资源也有属性。资源的一些例子是：

系统的用户
用户帐户
网络设备等

他们的资源URI可以设计如下：

/device-management/managed-devices 



/device-management/managed-devices/{device-id} 



/user-management/users



/user-management/users/{id}

为了更清楚起见，让我们将资源原型分为三类（文档、集合和存储）。那么，您最好始终将资源放入一个原型中，然后始终如一地使用其命名约定。

为了一致性，抵制设计多个原型混合资源的诱惑。

2.1.1. 文件

文档资源是一个类似于对象实例或数据库记录的单一概念。

在REST中，您可以将其视为资源集合中的单个资源。文档的状态表示通常包括具有值的字段和与其他相关资源的链接。

使用“单数”名称来表示文档资源原型。

http://api.example.com/device-management/managed-devices/{device-id}

http://api.example.com/user-management/users/{id}

http://api.example.com/user-management/users/admin

2.1.2. 收集

集合资源是服务器管理的资源目录。

客户可能会提出将新资源添加到集合中。然而，由集合资源来选择是否创建新资源。

集合资源选择它想要包含的内容，并决定每个包含资源的URI。

使用“复数”名称来表示集合资源原型。

/device-management/managed-devices

/user-management/users

/user-management/users/{id}/accounts

2.1.3. 商店

存储是客户端管理的资源存储库。存储资源允许API客户端将资源放入，将其取回，并决定何时删除它们。

存储从不生成新的URI。相反，每个存储的资源都有一个URI。当资源最初放入商店时，客户端选择了URI。

使用“复数”名称来表示存储资源原型。

/song-management/users/{id}/playlists

2.2.一致性是关键

使用一致的资源命名约定和URI格式，以实现最小的模糊性和最大的可读性和可维护性。您可以实现以下设计提示以实现一致性：

2.2.1.使用正斜杠（/）来指示分层关系

正斜杠（/）字符用于URI的路径部分，以指示资源之间的分层关系。例如

/device-management

/device-management/managed-devices

/device-management/managed-devices/{id}

/device-management/managed-devices/{id}/scripts

/device-management/managed-devices/{id}/scripts/{id}

2.2.2.不要在URI中使用尾随正斜杠（/）

作为URI路径中的最后一个字符，正斜杠（/）不会增加语义值，可能会混淆。最好把它从URI中删除。

http://api.example.com/device-management/managed-devices/ 

http://api.example.com/device-management/managed-devices         /*This is much better version*/

2.2.3.使用连字符（-）来提高URI的可读性

为了使您的URI易于人们扫描和解释，请使用连字符（-）字符来提高长路径段中名称的可读性。

http://api.example.com/devicemanagement/manageddevices/

http://api.example.com/device-management/managed-devices 	/*This is much better version*/

2.2.4.不要使用下划线（_）

可以使用下划线代替连字符作为分隔符——但根据应用程序的字体，下划线（_）字符可能会部分被遮挡或完全隐藏在某些浏览器或屏幕中。

为了避免这种混淆，请使用连字符（-）而不是下划线（_）。

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  //More readable



http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation  //Less readable

2.2.5.在URI中使用小写字母

方便时，在URI路径中应始终首选小写字母。

http://api.example.org/my-folder/my-doc       //1

HTTP://API.EXAMPLE.ORG/my-folder/my-doc     //2

http://api.example.org/My-Folder/my-doc       //3

在上述示例中，1和2是相同的，但3不是因为它使用大写字母的My-Folder。

2.3.不要使用文件扩展名

文件扩展名看起来很糟糕，不会增加任何优势。删除它们也会减少URI的长度。没有理由保留它们。

除了上述原因外，如果您想使用文件扩展名突出显示API的媒体类型，那么您应该依靠通过Content-Type标题传达的媒体类型来确定如何处理正文的内容。

/device-management/managed-devices.xml  /*Do not use it*/



/device-management/managed-devices 	/*This is correct URI*/

2.4.切勿在URI中使用CRUD函数名

我们不应该使用URI来指示CRUD函数。URI只能用于识别资源，而不是对它们进行任何独特的操作。

我们应该使用HTTP请求方法来指示执行了哪个CRUD函数。

HTTP GET /device-management/managed-devices  			//Get all devices

HTTP POST /device-management/managed-devices  			//Create new Device



HTTP GET /device-management/managed-devices/{id}  		//Get device for given Id

HTTP PUT /device-management/managed-devices/{id}  		//Update device for given Id

HTTP DELETE /device-management/managed-devices/{id}  	//Delete device for given Id

2.5.使用查询组件过滤URI集合

通常，您会遇到需要根据某些特定资源属性进行排序、过滤或限制的资源集合。

对于此要求，不要创建新的API——相反，在资源收集API中启用排序、过滤和分页功能，并将输入参数作为查询参数传递。例如

/device-management/managed-devices

/device-management/managed-devices?region=USA

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

/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date