「译」 REST 资源命名指南

前言

原文地址：REST Resource Naming Guide

资源的定义：
在 REST 中，主要数据表示为资源；REST 中信息的关键抽象是一种资源； 能够命名的任何信息均可以是资源：文档或图像，临时服务（例如“洛杉矶的今每天气”），其余资源的集合，非虚拟对象（例如人）等等。 换句话说，任何多是做者超文本引用目标的概念都必须符合资源的定义。 资源是对一组实体的概念映射，而不是与任何特定时间点的映射相对应的实体。

资源能够是单例或集合。
例如，“customers”是一个集合资源，“customer”是一个单例资源（在银行领域）。 咱们可使用URI“/ customers”来识别“customers”集合资源。 咱们可使用URI“/ customers / {customerId}”识别单个“客户”资源。

资源也能够包含子集合资源。
例如，可使用URN“/ customers / {customerId} / accounts”（在银行业务域中）来识别特定“客户”的子收集资源“帐户”。
相似地，子集合资源“账户”内的单个资源“账户”能够标识以下：“/ customers / {customerId} / accounts / {accountId}”。

REST API使用统一资源标识符（URI）来定位资源。
REST API设计者应该建立URI，将REST API的资源模型传达给潜在的客户端开发人员。 当资源命名良好时，API直观且易于使用。 若是作得很差，那么相同的API会感受难以使用和理解。
统一接口的约束部分经过URI和HTTP动词的组合来解决，而且根据标准和约定使用它们。
如下是为新API建立资源URI时可使用的一些提示。

使用名词表示资源

RESTful URI应该引用做为事物（名词）的资源而不是引用动做（动词），由于名词具备动词不具备的属性 - 相似于具备属性的资源。 资源的一些示例是：
系统的用户
用户账户
网络设备等
他们的资源URI能够设计以下：

http://api.example.com/device-management/managed-devices 
http://api.example.com/device-management/managed-devices/{device-id} 
http://api.example.com/user-management/users/
http://api.example.com/user-management/users/{id}
复制代码

为了更清楚，让咱们将资源原型划分为四个类别（文档，集合，存储和控制器），而后您应始终将资源放入一个原型，而后始终如一地使用它的命名约定。 为了资源的一致性，请抵制去设计资源的诱惑，这些资源将是不止一个原型的混合体。

文档

文档资源是一种相似于对象实例或数据库记录的单一律念。 在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
复制代码

集合

集合资源是服务器管理的资源目录。 客户能够建议将新资源添加到集合中。 可是，要由集合选择是否建立新资源。 集合资源选择它想要包含的内容，并决定每一个包含的资源的URI。
使用“复数”名称表示集合资源原型：

http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts
复制代码

存储

存储是客户端管理的资源库。 存储资源容许API客户端放入资源，将其退出，并决定什么时候删除它们。 存储永远不会生成新的URI。 相反，每一个存储的资源都有一个客户端在最初放入存储时选择的URI。
使用“复数”名称表示存储资源原型：

http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists
复制代码

控制器

控制器资源模拟程序概念。 控制器资源就像可执行函数，带有参数和返回值; 输入和输出。
使用“动词”表示控制器原型：

http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play
复制代码

保持一致性

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

使用正斜杠（/）表示层次关系

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

http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}
复制代码

不要在URI中使用尾部正斜杠（/）

做为URI路径中的最后一个字符，正斜杠（/）不会添加语义值，并可能致使混淆。 最好彻底放弃它们。

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

使用连字符（ - ）来提升URI的可读性

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

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
复制代码

不要使用下划线（_）

可使用下划线代替连字符做为分隔符 - 可是根据应用程序的字体，下划线（）字符可能会在某些浏览器或屏幕中被部分遮挡或彻底隐藏。
**为避免这种混淆，请使用连字符（ - ）而不是下划线（）。**

http://api.example.com/inventory-management/managed-entities/{id}/install-script-location  //More readable
http://api.example.com/inventory_management/managed_entities/{id}/install_script_location  //More error prone
复制代码

在URI中使用小写字母

方便时，URI路径中应始终首选小写字母。
RFC 3986 将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。

不要使用文件扩展名

文件扩展名看起来很糟糕，不会增长任何优点。 删除它们也会减小URI的长度。 没理由保留它们。
除了上述缘由，若是您想使用文件扩展突出显示API的媒体类型，那么您应该依赖于经过Content-Type标头传达的媒体类型来肯定如何处理正文的内容。

http://api.example.com/device-management/managed-devices.xml  /*Do not use it*/
http://api.example.com/device-management/managed-devices 	/*This is correct URI*/
复制代码

切勿在URI中使用CRUD函数名称

URI不该用于指示执行CRUD功能。 URI应该用于惟一标识资源，而不是对它们的任何操做。 应使用HTTP请求方法来指示执行哪一个CRUD功能。

HTTP GET http://api.example.com/device-management/managed-devices  //Get all devices
HTTP POST http://api.example.com/device-management/managed-devices  //Create new Device

HTTP GET http://api.example.com/device-management/managed-devices/{id}  //Get device for given Id
HTTP PUT http://api.example.com/device-management/managed-devices/{id}  //Update device for given Id
HTTP DELETE http://api.example.com/device-management/managed-devices/{id}  //Delete device for given Id
复制代码

使用查询参数过滤URI集合

不少时候，您会遇到须要根据某些特定资源属性对须要排序，过滤或限制的资源集合的要求。 为此，请不要建立新的API  - 而是在资源集合API中启用排序，过滤和分页功能，并将输入参数做为查询参数传递。 例如：

http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
复制代码