说明
- 原文链接
- 翻译:@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含有参数时该如何处理。