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。

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

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

REST API URI设计的7条规则