RESTful API设计系列四：URLs

说明

• 原文链接
• 翻译：@adolphlwq
• 项目地址
• tt：自动生成翻译模板
• 用时: 2h
• 

Entry Point

RESTful API有且只有一个入口点（entry point）。入口点的URL要告知API客户端，以便它们可以找到。

技术上讲，入口点可以被看作任何集合外的单个资源。通常入口点包含下列部分或全部信息：

• API版本信息，支持的特性等。
• 顶层集合列表。
• 单个资源列表。
• API设计者认为有用的信息，比如：操作状态的简短描述、统计信息等。

URL结构

API中的每个集合和资源都有自己的URL。URLs不能通过客户端来构造。客户端只能使用API生成的链接。

推荐的URL规范是在API入口点后添加可用的集合或者资源的路径。这最好通过例子来描述。下图表格来自Rails中的“路由”实现，使用“:name”URL变量风格。

URL Description /api The API entry point /api/:coll A top-level collection named “coll” /api/:coll/:id The resource “id” inside collection “coll” /api/:coll/:id/:subcoll Sub-collection “subcoll” under resource “id” /api/:coll/:id/:subcoll/:subid The resource “subid” inside “subcoll”

尽管子集合可能有任意层嵌套，以我个人经验，如果可以的话最好把嵌套深度限制在2以内。URLs越长，越难使用简单的命令行工具比如curl。

Relative vs Absolute

强烈建议API生成绝对地址的URLs。

理由主要是方便客户端，这样客户端就不要去匹配相对URL对应资源的绝对URL了。毕竟URL RPF中指定的检测基本URL的算法就已经非常复杂了。查找基本URL的方法之一是解析请求资源的URL。由于一个资源可能出现在多个URLs中（比如，资源作为集合的一部分出现在URL，或者单个资源），这样客户端记住每个URL是很大的开销。通过使用绝对URL就避免了这个问题。

URL模板

已经有关于URL模板的草案了。当目标URL中存在查询参数时，URL模板会很有帮助。即便如此我还是推荐保守（conservative）使用模板。目前为止URL模板唯一的使用案例是在集合中搜索。搜索条件可以作为GET风格的查询参数附加到集合URL后面。

我建议使用URL模板规范的”字面扩展“（literal expansion）部分，因为我认为规范的”表达式扩展“部分非常复杂，几乎没有优势。

变量

有时你的工作需要处理资源中的变量部分。以我们的RHEV-M API为例，当虚拟机运行时需要更新虚拟机里面的一些属性。这相当于资源的热插拔（This amounts to a hot plug/unplug of the resource），这与改变已经保存的表示是完全不同的操作。好的实现方法是在URL中使用”;variant”，比如：

URL Description /api/:coll/:id;saved Identifies the saved variant of a resource. /api/:coll/:id;current Identifies the current variant of a resource.

RFC3986允许使用分号来提供特定于路径段的选项。使用”?variant”格式查询参数的优势是，该格式只能用于路径段。

译者说

本文作者介绍了API的入口点（entry point），推荐使用RESTful API的绝对URL。同时介绍了URL含有参数时该如何处理。