REST API接口命名的最佳实践

REST API 是整合多个应用程序的强大工具。虽然 REST API 非常有用，但创建和部署它们到生产环境中是一个非常复杂且耗时的过程。如果您正在构建自己的 REST API，您应该熟悉一些命名 REST API 端点的行业最佳实践。对于许多开发人员来说，使用开发平台是一种很好的入门方式。它简化了开发流程并确保您能够立即开始。

以下是我们建议的 REST API 端点遵循的命名约定：

REST API 端点应遵循良好的命名实践，以提高可用性、可维护性和可扩展性。
使用名词（最好是复数）来表示资源，与 REST 架构风格保持一致。
避免端点名称中的深度嵌套和不必要的特殊字符。
用连字符分隔单词并使用小写字母以避免混淆。
不要在 URI 中使用文件扩展名。使用 Content-Type 实体标头来表示原始文件类型。
REST API 端点中一致的命名约定可增强可读性、理解力和故障排除，并促进增长和可扩展性。

什么是 REST API 端点？

REST API 端点是 Web 服务中通信的基石，充当交互点，其中配置了特定的 URL 以接收 Web 请求。它们允许不同的软件应用程序通过定义它们可以使用的方法和数据格式来相互通信。每个端点都是一个特定的 URL，API 可以在其中访问所需的资源（例如服务器数据），并使用标准 HTTP 方法（包括 GET、POST、PUT 和 DELETE）执行操作。适当地命名这些端点对于可读性、可维护性和易于集成至关重要，从而确保无缝的用户体验。

API 端点命名最佳实践

当有一条清晰、完善的路径可供遵循时，浏览 API 的数字迷宫就会变得容易得多。这是在命名 REST API 端点时采用最佳实践的本质。REST（即表述性状态转移）提供了一组架构约束，可增强 Web 服务的性能、可扩展性和可修改性。命名约定是这些约束的一个组成部分，它提供了一种系统的方式来构建 API 端点，使其可预测且易于理解。虽然这看起来像是一个小细节，但我们命名端点的方式会对用户体验、可维护性和 API 的整体成功产生深远影响。

使用名词命名 URI

所有 REST API 都有一个可以访问的 URL，例如 https://api.example.com 。此 URL 的子目录表示不同的 API 资源，可以使用统一资源标识符 (URI) 访问。对于开发人员来说，这是一种确保名称有意义且任何人都能理解的简单方法。例如，URI https://api.example.com/ users 将返回包含特定服务的用户的列表。Web API 使人们更容易了解正在使用哪些 Web 服务。

一般来说，URI 应该用名词来命名，以指定资源的内容，而不是为正在执行的功能添加动词。例如，您应该使用 https://api.example.com/users ，而不是 https://api.example.com/ getUsers。这是因为 CRUD（创建、读取、更新、删除）功能应该已经在 HTTP 请求中指定（例如 HTTP GET https://api.example.com/users）。没有必要重复这些信息，这使 URI 易于阅读，同时显示它是所需的 Get 方法。内容类型标头是命名 URI 的好方法。在极少数情况下，您可以使用 HTTP 动词，但最好坚持使用名词作为其余端点名称。

我应该将 Rest API 命名为复数还是单数？

使用名词命名 URI 是 REST API 命名的最佳实践，但您可能想知道复数名词还是单数名词最好。什么时候应该使用单数名词或复数名词？一般来说，您应该使用复数名词来命名 URI。例外情况是当您有一个明显是单数的概念时，这种情况很少发生。（例如，对于管理用户， https://api.example.com/users/ admin ）。

使用清晰、完整且直观的名称

命名 REST API 端点时，应使用直观且易于理解的 URI 名称。考虑一下那些以前从未使用过您的 API 的人检查 URI 的情况。他们应该能够轻松猜出使用了哪些单词以及它们的结构。您绝对应该避免使用缩写和速记（例如 https://api.example.com/users/123/fn 而不是 https://api.example.com/users/123/first-name）。在某些情况下，某个事物的接受或流行术语就是缩写，这意味着您可以使用它。（例如 https://api.example.com/users/ids 而不是 https://api.example.com/users/identification-numbers）。记住要保持足够简单，以便任何不熟悉您的 API 的人都可以轻松猜出 URI。如果每个人都使用相同的方法来命名他们的 REST API 端点，那么使用起来就会更容易。

您正在命名资源，该资源可能是单例或集合。最终用户一看到名称，就会知道它到底是什么。例如，您可以使用“customer”或“users”作为资源名称。还需要定义子集合。最终看起来像“/users/client-id/accounts/account-id”。如您所见，它清楚地显示了 URI 的层次结构，即使有人不熟悉您的 API，也可以跟踪资源。

使用正斜杠表示 URI 层次结构

REST API 通常采用层次结构。例如，https://api.example.com/users/123/first-name 将检索 ID 号为 123 的用户的名字。应使用正斜杠（“/”）字符来导航此层次结构并指示您所在的位置。在 URI 中从左到右移动时，它会从一般移动到具体。

虽然正斜杠适合表示 API 的层次结构，但它们在 URL 的末尾并不是必需的。添加这个多余的斜杠会增加复杂性，而不会增加清晰度。例如，您应该使用 https://api.example.com/users，而不是 https://api.example.com/users/。

用连字符分隔单词

当 REST API 端点包含多个单词（例如 https://api.example.com/users/123/first-name）时，应使用连字符分隔单词。这是使 URI 更易于阅读的好方法，也是每个人都能理解的通用方法。

人们普遍认为，连字符比下划线（例如 first_name）或驼峰式大小写（例如 firstName）更清晰、更方便用户使用，后者由于使用大写字母而不被推荐（见下文）。连字符易于输入，并且所有开发人员都在同一页面上，它可以简化 URI 以确保每个人都可以访问。

使用小写字母

尽可能在 API URL 中使用小写字母。这主要是因为 URI 标准的 RFC 3986 规范指出 URI 区分大小写（URL 的方案和主机组件除外）。URI 的小写字母被广泛使用，也有助于避免因大小写不一致而引起的混淆。如果您添加大写字母，您应该意识到这会引起混淆，并且通常会导致用户错误。

避免使用特殊字符

特殊字符不仅没有必要，而且可能会让熟悉 API 设计和命名的用户感到困惑。它们并非人人都能轻松使用，而且技术上也很复杂。由于 URL 只能使用 ASCII 字符集发送和接收，因此所有 API URL 都应仅包含 ASCII 字符。

此外，请尽量避免使用“不安全”的 ASCII 字符，这些字符通常经过编码以防止混淆和安全问题（例如，空格字符为“%20”）。URL 的“不安全”ASCII 字符包括空格字符（“ “”）以及括号（“[]”）、尖括号（“<>”）、大括号（“{}”）和竖线（“|”）。尽可能保持名称简单，这样就不会出现任何问题。在大多数情况下，这些与 HTTP 方法相同。

避免文件扩展名

虽然 API 调用的结果可能是特定的文件类型，但文件扩展名（例如 .HTML）在 URI 中被视为不必要的，因为它们会增加长度和复杂性。例如，您应该使用 https://api.example.com/users 而不是 https://api.example.com/users.xml。事实上，如果您稍后更改结果的文件类型，使用文件扩展名可能会给最终用户带来问题。例如，您不需要使用 node.js 或类似文件。它可以简化。

URI 中的文件扩展名通常会造成混淆，如果不知道 URI，也会使直观理解 URI 变得更加困难。文件扩展名不需要包含在内，还有其他方法可以指示文件类型。这些不应包含在 REST API 设计和名称中。

如果您想要指定结果的文件类型，则可以使用 Content-Type 实体标头。这可以让用户知道原始资源使用了哪种媒体类型。这并非总是必要的，但如果您希望保留原始文件类型的记录，则可以使用此方法。

REST API 端点命名保持一致

选择一种命名 API 端点的系统并坚持使用。您应该记录您的方法，以便与您一起工作的每个人都知道命名协议。当您的名称一致时，这可以确保整个系统统一。使用 API 的每个人都会发现使用它们很容易。如果他们不确定特定的 URI，他们可以根据命名协议假设它是什么。

保留所有记录。虽然有一些普遍理解的指导方针，但您可能希望将流程正式化。当新人加入您的团队时，他们可以快速访问 URI 命名协议并遵循这些协议以确保一致性。

命名 REST API 端点时应避免的常见错误

REST API 的清晰度和成功在很大程度上取决于您如何命名端点。虽然有一些推荐的做法可供遵循，但了解和避免常见的命名错误也同样重要。以下是一些常见的错误做法。

使用非描述性端点名称

REST API 端点应明确标识特定资源。如果您的端点名称含糊不清或不具描述性，则可能会让开发人员和用户感到困惑。坚持使用简单、直观的名称，清晰地反映相关资源。避免使用可能不是所有用户都熟悉的神秘缩写、首字母缩略词或行业术语。

混合大小写样式

根据RFC 3986的规定，URI 区分大小写。API URL 中混合使用大小写字母可能会导致误解和潜在错误。始终在端点名称中使用小写字母，以保证一致性并避免潜在问题。

在端点名称中包含动词

REST 架构的基石是使用 HTTP 方法（动词）来操作资源（名词）。因此，在端点名称中加入动词是一种不好的做法，因为 HTTP 请求方法应该已经指定了执行的功能。在端点名称中包含动词可能会导致冗余和混乱。

未能正确版本化你的 API

API 版本控制对于在 API 不断发展时保持向后兼容性至关重要。如果未在端点中包含版本控制，则可能导致对用户产生重大影响的更改。务必在端点中包含版本（例如“v1”），以确保在 API 不断发展时顺利过渡。

良好 API 命名实践的好处

为 API 端点建立有效、清晰且一致的命名约定可以大大增强应用程序的可用性、可维护性和可扩展性。让我们深入探讨正确命名 REST API 端点的好处。

1. 增强可读性和理解力

命名良好的 API 端点可以立即告诉您从中可以期待什么，从而提高可读性和理解力。例如，GET请求/users直观地暗示获取用户列表。这种清晰度简化了新开发人员的学习曲线并增强了团队之间的协作。

2. 提高一致性

一致的命名约定可让您的 API 更可预测且更易于使用。开发人员可以预测端点的结构，从而减少错误并加快 API 集成速度。

3. 更容易排除故障

如果出现问题，命名良好的端点可以加快故障排除过程。当端点反映其功能时，更容易找到和纠正问题，从而提高生产率并减少停机时间。

4. 促进增长和可扩展性

随着应用程序的增长，API 端点的数量也会随之增加。强大的命名约定有助于有效管理这种增长，确保新端点与现有端点顺利集成，从而促进可扩展性。

5. 更好的用户体验

对于 API 的客户来说，清晰直观的端点意味着更顺畅、更愉快的体验。使用您的 API 的开发人员会欣赏结构良好、命名合理的端点背后的周到，使他们更有可能继续使用您的服务。

缓存策略

通过存储经常访问的数据，API 将响应更快，并可能减少后端负载，从而带来更好的用户体验。

缓存通过比从数据库或服务器获取数据更快的速度检索数据来提高性能。这种速度对于提供快速响应的应用程序非常重要，因为用户希望立即进行交互。缓存还可以通过处理来自缓存的重复请求来减少服务器负载，从而减少数据库查询和计算。

可扩展性是另一个关键优势。有效的缓存有助于管理高流量，这将确保您的 API 能够扩展以满足不断增长的需求，而不会影响性能。这对于经历快速增长或突然流量激增的应用程序来说非常重要。

根据不同的需求，可以实现几种不同的缓存策略：

内存缓存：将数据存储在服务器的 RAM 中，以实现超快速访问。非常适合频繁访问的数据，如会话信息或常查询的数据库记录。常用工具包括 Redis 和 Memcached。
HTTP 缓存标头Cache-Control：使用、Expires、ETag和等标头控制 API 响应的缓存行为Last-Modified。这些标头管理客户端和代理应缓存响应的时间，从而减少服务器请求的数量。
分布式缓存：将缓存数据存储在多个节点或服务器上，提供冗余和可扩展性。适用于流量大的大规模应用程序。常用的工具有 Redis（集群模式）和 Varnish（反向代理）。
反向代理缓存：将缓存职责从 API 服务器转移到反向代理服务器（如 Varnish）。此设置会缓存来自后端的响应并将其直接提供给客户端，从而缩短响应时间并减少后端负载。