REST API URI设计的7条规则

REST API URI设计的7条规则

这七个简单的规则将帮助您编写可读的，无冲突的URI，以传达全部必要的资源信息。

经过

盖·莱文

在研究REST API URI设计的规则以前，让咱们快速概述一下咱们将要讨论的一些术语。

URIs

REST API使用统一资源标识符（URI）来寻址资源。在今天的网络，URI设计范围从明确传达，如API的资源模型杰做http://api.example.com/louvre/leonardo-da-vinci/mona-lisa，
对那些更难为人们所了解，如http://api.example.com/68dd0-a9d3-11e0-9f1c-0800200c9a66。

蒂姆·伯纳斯·李（Tim Berners-Lee）在他的“ Web体系结构公理”列表中包括有关URI不透明的注释：“惟一可使用标识符的是引用对象。当不进行解引用时，您不该查看URI字符串的内容以获取其余信息。”

客户必须遵循Web的连接范例，并将URI视为不透明的标识符。

REST API设计人员应建立URI，以将REST API的资源模型传达给潜在的客户端开发人员。在本文中，我将尝试介绍REST APIURI的一组设计规则。

在深刻了解这些规则以前，本节介绍的有关URI格式的文字与URI的格式有关。RFC 3986定义了通用URI语法，以下所示：

URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

规则1

URI中不该包含结尾的正斜杠（/）。

这是要遵循的最重要的规则之一，由于URI路径中的最后一个字符，正斜杠（/）不会增长语义值，而且可能引发混乱。REST API不该包含斜线，也不该将其包含在它们提供给客户端的连接中。

许多Web组件和框架将同等对待如下两个URI：

http://api.canvas.com/shapes/  
http://api.canvas.com/shapes

可是，URI中的每一个字符都会计入资源的惟一标识。

两个不一样的URI映射到两个不一样的资源。若是URI不一样，则资源也不一样，反之亦然。所以，REST API必须生成并传递干净的URI，而且不该容忍任何客户端错误地识别资源的尝试。

更多宽容的API能够将客户端重定向到URI，而不会在末尾加反斜杠（它们也可能会返回301 –“永久移动”，用于从新定位资源”）。

规则2

必须使用正斜杠分隔符（/）表示层次关系。

URI的路径部分使用正斜杠（/）字符表示资源之间的层次关系。例如：http://api.canvas.com/shapes/polygons/quadrilaterals/squares

规则3

应使用连字符（-）来提升URI的可读性。

为了使您的URI易于人们扫描和解释，请使用连字符（-）来提升长路径段中名称的可读性。在英语中使用空格或连字符的任何地方，都应在URI中使用连字符。

例如：http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

规则4

URI中不该使用下划线（_）。

文本查看器应用程序（浏览器，编辑器等）一般在URI下划线，以提供可单击的可视提示。根据应用程序的字体，下划线（_）字符可能会被此下划线部分掩盖或彻底隐藏。

为避免这种混淆，请使用连字符（-）代替下划线。

规则5

在URI路径中应首选小写字母。

方便时，URI路径中最好使用小写字母，由于大写字母有时会引发问题。RFC 3986将URI定义为区分大小写，但方案和主机组件除外。

例如：

1）http://api.example.com/my-folder/my-doc

2）HTTP://API.EXAMPLE.COM/my-folder/my-doc 

上面的URI很好。URI格式规范（RFC 3986）认为此URI与URI＃1相同。

3）http://api.example.com/My-Folder/my-doc

该URI与URI 1和URI 2不一样，这可能致使没必要要的混淆。

规则6

文件扩展名不该包含在URI中。

在Web上，句点（。）字符一般用于分隔URI的文件名和扩展名部分。REST API不该在URI中包含人工文件扩展名，以指示消息的实体主体的格式。相反，它们应该依靠经过Content-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标头。

为了实现简单的连接和调试，REST API能够经过查询参数支持媒体类型选择。

规则7

端点名称应为单数仍是复数？

保持简单规则在此处适用。尽管内部语法专家会告诉您使用复数形式描述资源的单个实例是错误的，但务实的答案是保持URI格式的一致性，并始终使用复数形式。

没必要处理不规则复数形式（person/people, goose/geese），使API消费者的生活更美好，是对API提供商实现（如最现代化的框架经过 controller 处理 /students 和 /students/3248234 很容易）。

可是您如何处理关系？若是关系只能存在于另外一个资源中，则RESTful原则将提供有用的指导。让咱们来看一个例子。一个学生有许多课程。这些课程在逻辑上映射到 /students 端点，以下所示：

http://api.college.com/students/3248234/courses -检索ID为3248234的学生学习的全部课程的列表。
http://api.college.com/students/3248234/courses/physics -检索ID为3248234的学生的课程中的物理。

结论

在设计REST API服务时，必须注意资源。这些由URI定义。

您正在构建的一个或多个服务中的每一个资源将至少具备一个标识它的URI。最好是该URI有意义并充分描述资源。URI应该遵循可预测的层次结构，以加强易懂性，从而加强可用性：从统一性的意义上是可预测的，在数据​​具备结构关系的意义上则是分层的。

RESTful API是为消费者编写的。URI的名称和结构应向这些使用者传达含义。经过遵循上述规则，您将使用更快乐的客户端来建立更简洁的REST API。这不是REST规则或约束，可是它加强了API。

我还建议您看看这些准则。

为您的客户而不是您的数据设计。