REST url 路径参数命名约定

Question

REST url 中的通用参数名称是否有任何命名约定？

在我的示例中，我想根据部门 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，可读性可能？)绑定(bind)资源生命周期(部门/员工示例)，您也可能想要进行嵌套。如果您这样做，也许您应该将嵌套路径视为仅别名:

• 对于/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']

请注意 Link header 包含 2 个链接，其中一个用于搜索以及获取下一页员工的信息 (rel=next")。

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

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

人们可以使用文件系统来绘制/模拟 RESTfull API:在硬盘上创建文件夹、文件(可能还有符号链接(symbolic link)/别名/快捷方式)，浏览它们、更改它们、冲洗并重复，直到您对结构满意为止:)

$ 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