Question

ReST网址中是否有通用参数名称的命名约定？

在我的示例中，我希望根据部门ID或部门所在的组织ID获取部门的地址。

所以url路径参数名称deptOrOrgId - 根据命名约定或我应该使用诸如sectionID或officeID之类的通用名称来表示部门ID和组织ID吗？

感谢。

Answer 1

以下是有关REST API中链接和路径设计的其他一些约定，可能有所帮助：

<强> 1。路径参数与查询字符串

路径参数（/parent/child1;child2）很酷，但查询字符串可以表达路径参数，标准和显式。例如：
- /parent?id=child1&id=child2
- 或/parent?id=child1;child2 ...等

<强> 2。多元或单数

对每个集合（或表或文件夹）使用复数是好的，因为它暗示资源是其他资源的列表

/users，/users/user1，/users?active=true

嵌套资源：默认为无嵌套，除非存在强关系

如果候选子资源可以独立于父级存在，则嵌套没有意义，因为您可能最终会有多条路径用于同一事物：

/departments/{departments}/employees/{employee}
/branch-offices/{branch}/employees/{employee}
/employees/{employee}

对于后者，您可以完成所有其余的工作：

部门中的所有员工/employees?department={department}
分行/employees?branch={branch}

第3。仅在强关系上使用嵌套

当嵌套资源不能存在于父级之外时（例如，在UML术语中为Composition）

/books/{book}/pages/{page}如果没有指定图书，您将永远不会寻找页面
/players/{player}/stats}（再次，这取决于您的域名模型）

<强> 4。好的...在不那么强的关系上使用嵌套路径，但将它们视为别名

当然，即使没有强关系，或者出于某种原因（DX，可读性可能？），资源生命周期（部门/员工示例）也可能需要嵌套。如果你这样做，也许你应该将嵌套路径视为仅为别名：

for /departments/{department}/employees
内部重写/employees?department={department}

<强> 5。如果你想要HATEOAS，那么路径设计不应该是首要任务

另一方面，如果您想要拥抱REST HATEOAS，则客户端可读性并不重要。 API客户端不应该猜测您的链接或模板的硬编码。相反，您的API提供客户端遵循的链接。例如：

根路径可能会列出所有主要链接：

GET /

200 OK
Content-Type: application/json
{
   links:{
       "employees":"/url-for-employees{?department,branch,name}"
       "departments":"/them-deps"
   }
}

在这个例子中，链接是故意丑陋的。关键的员工实际上是URL template，带有可选参数。

然后，客户端API会查找带有密钥employee的链接（在本例中为/ url-for-employees） - 无论它看起来如何 - 并调用它：

GET /url-for-employees

200 OK
Content-Type: application/json
Link: </url-for-employees{?department,branch,name}>; rel="search",
</url-for-employees?page=2>; rel="next"

['body is an array containing the first set/page of employees']

注意链接头包含2个链接，一个用于搜索和一个获得下一页员工（rel = next＆＃34;）。

HATEOS的好处超出了这个范围，但至少有一个是你可以自由地重新组织你的路径而不破坏API客户端

<强> 5。最后，在您的文件系统上尝试

可以使用文件系统来草绘/模拟RESTfull API：在您的硬盘上创建文件夹，文件（也可能是符号链接/别名/快捷方式），浏览它们，更改它们，冲洗并重复，直到您对结构感到满意为止：）

$ mkdir myapi
$ cd myapi
$ touch index.json
$ mkdir employees
$ touch employees/index.json
$ touch employees/smith.json
$ mkdir departments
$ touch departments/index.json
$ touch departments/accounting.json
$ mkdir departments/accounting
$ mkdir departments/accounting/employees
$ ln -s employees/smith.json departments/accounting/employees/smith.json
$ ls -l departments/accounting/employees
smith.json -> employees/smith.json

Answer 2

检查部分资源URI示例 Naming Convention Tutorial。希望你能得到答案。

此外，这个book定义了网址设计的三个基本规则，它们是一个很好的起点：

•使用路径变量对层次结构进行编码：/ parent / child

•在路径变量中放置标点字符以避免暗示   不存在的层次结构：/ parent / child1; child2

•使用查询变量来暗示算法输入，例如：   / search？q = jellyfish＆amp; start = 20

其他指南包括：

•理想情况下，URI不会随时间而变化。

•通过密钥提供唯一可识别资源的服务应该   使用基本的休息符号（例如/ accounts /（accountid））

•应使用提供可选搜索/过滤功能的服务   查询参数？ key1 = value＆amp; key2 =值表示法（例如   / instruments？ticker = FT）

•期望通过GET强制参数的服务应该将它们作为   路径变量（例如/ accounthistory /（fromdate）/（todate）

•所有其他服务名称应使用严格的低案例名称（例如   / client）

•URI的元素应映射到业务实体和   映射应该是一致的。例如，一个名为的商业实体   contentpartner应始终称为contentpartner（s）   在所有URI中（而不是伙伴，cp等的混合）。一个好的开始   point将是域对象的名称。

•未定义资源但限定资源的参数（例如区域设置）   它不应成为数据翻译的一部分   普通的URI空间。考虑使用标头或可选查询   这些参数

•使用名词，而不是动词。 REST的力量来自于这个事实   有一个有限的动词集（操作）与一大组   名词（或资源）。因此，这些名词的方式   建造非常重要。

•避免使用后缀。在设计URI时，它们引用是至关重要的   对于正在操作的东西而不是操作   被执行。其次，客户对资源感兴趣 -   而不是为服务提供动力的服务器软件的实现。   希望避免使用诸如.jsp或.aspx之类的后缀。

•使用接受标题进行内容协商

•保持直观。 URI应该是人类可读或可猜测的。该   最简单的方法是构造一个URI层次结构，进行分组   相关项目在一起。这种类别和子类别的模式是   很容易理解。

ReST url路径参数命名约定

2 个答案: