原文:http://blog.restcase.com/7-rules-for-rest-api-uri-design/
作者:Guy Levin
翻译:Aladdin
在了解REST API URI设计的规则之前,让我们快速浏览一些我们将要讨论的术语。
REST API使用统一资源标识符(URI)来寻址资源。在当今互联网上,充斥着各种各样的URI设计规则,既有像//api.example.com/louvre/leonardo-da-vinci/mona-lisa这样能够清楚的传达API资源模型的文章,也有很难理解的文章,例如://api.example.com/68dd0-a9d3-11e0-9f1c-0800200c9a66 ;Tim Berners-Lee在他的“Axioms of Web Architecture”一文中将URI的不透明度总结成一句话:
唯一可以使用标识符的是引用对象。在不取消引用时,就不应该查看URI字符串的内容以获取其他信息。
——蒂姆·伯纳斯 - 李
客户端必须遵循Web的链接范例,将URI视为不透明标识符。
REST API设计人员应该在考虑将REST API资源模型传达给潜在的客户端开发者的前提下,创造URI。在这篇文章中,我将尝试为REST API URI 引入一套设计规则。
先跳过规则,URI的通用语法也适用与本文中的URI。RFC 3986定义了通用URI语法,如下所示:
URI = scheme “://” authority “/” path [ “?” query ][ “#” fragment ]
这是作为URI路径中处理中最重要的规则之一,正斜杠(/)不会增加语义值,且可能导致混淆。REST API不允许一个尾部的斜杠,不应该将它们包含在提供给客户端的链接的结尾处。
许多Web组件和框架将平等对待以下两个URI:
http://api.canvas.com/shapes/
http://api.canvas.com/shapes
但是,实际上URI中的每个字符都会计入资源的唯一身份的识别中。
两个不同的URI映射到两个不同的资源。如果URI不同,那么资源也是如此,反之亦然。因此,REST API必须生成和传递精确的URI,不能容忍任何的客户端尝试不精确的资源定位。
有些API碰到这种情况,可能设计为让客户端重定向到相应没有尾斜杠的URI(也有可能会返回301 - 用来资源重定向)。
URI的路径中的正斜杠(/)字符用于指示资源之间的层次关系。
例如:
(http://api.canvas.com/shapes/polygons/quadrilaterals/squares ;
为了使您的URI容易让人们理解,请使用连字符( - )字符来提高长路径中名称的可读性。在路径中,应该使用连字符代空格连接两个单词 。
例如:
http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post
一些文本查看器为了区分强调URI,常常会在URI下加上下划线。这样下划线(_)字符可能被文本查看器中默认的下划线部分地遮蔽或完全隐藏。
为避免这种混淆,请使用连字符( - )而不是下划线
方便时,URI路径中首选小写字母,因为大写字母有时会导致一些问题。RFC 3986将URI定义为区分大小写,但scheme 和 host components除外。
例如:
http://api.example.com/my-folder/my-doc
HTTP://API.EXAMPLE.COM/my-folder/my-doc
这个URI很好。URI格式规范(RFC 3986)认为该URI与URI#1相同。
http://api.example.com/My-Folder/my-doc
而这个URI与URI 1和2不同,这可能会导致不必要的混淆。
在Web上,(.)字符通常用于分隔URI的文件名和扩展名。
REST API不应在URI中包含人造文件扩展名,来指示邮件实体的格式。相反,他们应该依赖通过Content-Type中的header传递media type,来确定如何处理正文的内容。
http://api.college.com/students/3248234/courses/2005/fall.json
http://api.college.com/students/3248234/courses/2005/fall
如上所示:不应使用文件扩展名来表示格式。
应鼓励REST API客户端使用HTTP提供的格式选择机制Accept request header。
为了是链接和调试更简单,REST API应该支持通过查询参数来支持媒体类型的选择。
keep-it-simple的原则在这里同样适用。虽然一些”语法学家”会告诉你使用复数来描述资源的单个实例是错误的,但实际上为了保持URI格式的一致性建议使用复数形式。
本着API提供商更容易实施和API使用者更容易操作的原则,可以不必纠结一些奇怪的复数(person/people,goose/geese)。
但是应该怎么处理层级关系呢?如果一个关系只能存在于另一个资源中,RESTful原则就会提供有用的指导。我们来看一下这个例子。学生有一些课程。这些课程在逻辑上映射到学生终端,如下所示:
http://api.college.com/students/3248234/courses - 检索id为3248234的学生学习的所有课程的清单。
http://api.college.com/students/3248234/courses/physics -检索该学生的物理课程
当你在设计REST API服务时,您必须注意这些由URI定义的资源。
正在构建的服务中的每个资源将至少有一个URI标识它。这个URI最好是有意义的,且能充分描述资源。URI应遵循可预测的层次结构,用来提高其可理解性,可用性:可预测的意义在于它们是一致的,它的层次结构在数据关系上是有意义的。
RESTful API是为使用者编写的。URI的名称和结构应该能够向使用者传达更清晰的含义。通过遵循上述规则,您将创建一个更清晰的的REST API与更友好的客户端。这些并不是REST的规则或约束,仅仅是API的增强和补充。
我也建议你来看看http://blog.restcase.com/5-basic-rest-api-design-guidelines/这篇文章。
最后,望大家牢记:你在为你的客户端设计API URI,而不仅仅是为你的数据。
联系客服