ReST网址中是否存在通用参数名称的命名约定？
在我的示例中,我希望根据部门ID或部门所在的组织ID获取部门的地址.
所以url路径参数名称deptOrOrgId - 它是基于命名约定有效还是我应该使用诸如sectionID或officeID之类的通用名称来表示部门ID和组织ID？
谢谢.
red*_*ben 15
以下是有关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术语例如)
/books/{book}/pages/{page} 如果没有指定书籍,您永远不会寻找页面/players/{player}/stats} (再次,这取决于您的域模型)好吧......在不那么强大的关系上使用嵌套路径,但将它们视为别名
当然,即使没有强关系,或者由于某种原因(DX,可读性可能？),资源生命周期(部门/员工示例)也可能需要嵌套.如果你这样做,也许你应该将嵌套路径视为仅为别名:
/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模板.
然后客户端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").
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
请查看\n命名约定教程的资源 URI 示例部分。希望您能得到答案。
\n\n此外，本书定义 了 url 设计的三个基本规则，这是一个很好的起点：
\n\n\n\n\n\xe2\x80\xa2 使用路径变量编码层次结构：/parent/child
\n\n\xe2\x80\xa2 将标点符号放在路径变量中以避免暗示\n不存在的层次结构：/parent/child1;child2
\n\n\xe2\x80\xa2 使用查询变量暗示算法的输入，例如：\n /search?q=jellyfish&start=20
\n
其他指南包括：
\n\n\n\n\xe2\x80\xa2 URI 理想情况下不应随时间变化。
\n\n\xe2\x80\xa2 通过密钥提供唯一可识别资源的服务应\n 使用基本剩余表示法（例如 /accounts/(accountid) ）
\n\n\xe2\x80\xa2 提供可选搜索/过滤功能的服务应使用\n 查询参数 ? key1 = 值 & key2 = 值符号（例如\n /instruments?ticker=FT）
\n\n\xe2\x80\xa2 需要 GET 强制参数的服务应将它们作为\n 路径变量（例如 /accounthistory/(fromdate)/(todate)
\n\n\xe2\x80\xa2 所有其余服务名称应使用严格的小写名称（例如\n /client）
\n\n\xe2\x80\xa2 URI 的元素应映射到业务实体，并且映射应一致。例如，名为 contentpartner 的业务实体在所有 URI 中应一致被称为 contentpartner（而不是合作伙伴、cp 等的混合）。一个好的起点是域对象的名称。
\n\n\xe2\x80\xa2 不定义资源但限定资源的参数（例如，输入数据翻译的语言环境）不应构成正常 URI 空间的一部分。考虑使用标头或可选的查询参数\n
\n\n\xe2\x80\xa2 使用名词，而不是动词。REST 的力量来自于这样一个事实：有限的动词集（操作）与大量名词（或资源）相结合。因此，这些名词的构造方式非常重要。
\n\n\xe2\x80\xa2 避免后缀。设计 URI 时，最重要的是它们引用正在操作的事物，而不是正在执行的操作。其次，客户端感兴趣的是资源 -\n 而不是支持服务的服务器软件的实现。\n 最好避免使用 .jsp 或 .aspx 等后缀。
\n\n\xe2\x80\xa2 使用 Accepts 标头进行内容协商
\n\n\xe2\x80\xa2 保持直观。URI 应该是人类可读或可猜测的。最简单的方法是构建一个 URI 层次结构，将相关项分组在一起。这种类别和子类别的模式非常容易理解。
\n
| 归档时间： |
|
| 查看次数： |
22443 次 |
| 最近记录： |