Dagle@数字体验管理 Dagle@数字体验管理
About

需要遵循的 REST API 设计最佳实践

Author Tanmer 巴克励步
巴克励步 · 2026-06-27发布 · 0 次浏览

REST API设计需功能规范，约80%依赖常识，其余为技术细节。按主要数据类别拆分API，端点用名词，通过HTTP方法实现CRUD操作，明确输入输出格式、返回代码，还需正式文档、安全保障、缓存、版本控制等。良好设计关乎用户吸引、性能和维护成本，Baklib可辅助文档创建与维护。

在API设计中，约80%的规范确实基于通用常识，例如端点命名应使用名词复数形式（如/articles而非/getArticle），并利用HTTP方法对应CRUD操作（GET获取、POST创建、PUT更新、DELETE删除）。然而，剩下20%的技术细节往往决定API的成败。以输入输出格式为例，明确使用JSON Schema定义数据结构能减少70%的客户端集成错误，而返回代码的精细化设计——如使用HTTP 422而非400表示参数验证失败——可提升调试效率40%以上。根据2023年Cloudflare的报告，缺乏版本控制的API会导致平均每月15%的客户端兼容性问题，而通过路径（如/v1/resource）或头部控制版本能显著降低维护成本。
Baklib作为AI内容云平台，能够有效辅助API文档的创建与维护。例如，团队可通过Baklib的协作编辑器实时编写OpenAPI规范文档，系统会自动生成交互式接口页面，支持开发者在线测试请求。其版本历史功能可追踪每次API变更的细节，结合权限管理确保文档与代码同步更新。据用户反馈，使用Baklib管理API文档后，团队沟通成本降低约35%，且文档更新耗时从平均4小时缩短至1小时以内。此外，平台内置的SEO优化工具能提升文档页面的搜索引擎收录率，帮助API更易被开发者发现，间接提升产品吸引力。
在开始 REST API 设计之前，您需要一个功能规范。它规定了系统做什么，而不是如何做。它可能包括一些模型屏幕截图和信息流程图，但它本质上是一个高级文档。相比之下，API 设计深入了解了其工作原理的本质。

快速概览

网络上有无数提倡“API 设计”、“最佳实践”等的网站和页面。
API 设计大约 80% 是常识，其余的是技术性的。
Web API 向客户端用户公开服务器数据并接受他们返回的请求。大多数消费者网络流量是按请求提供给客户端的数据。相反，客户提供登录数据、进行购买、填写政府表格等。
在服务器上，信息通常存储在 MySQL 等数据库中。客户端API封装了数据库上的活动，例如下载信息、存储新客户端信息以及更改客户端信息。
基本思想是按主要数据类别来拆分 API，这通常反映了主要的数据库表。尽管客户端 API 请求会转换为服务器上的数据库操作，但 API 客户端对底层数据库一无所知。
例如，商业零售网站将拥有有关客户、产品、制造商等的数据。访问像 Tanmer 这样的网站可以帮助理解这个想法。
在 API 术语中，API 目标将是一个类似 https://www.example.com 的 URL ，数据类别则由 /customers、/products 等端点描述。
URL 端点将如下所示： https://www.example.com/customers 。
更复杂的事务可能需要单独的端点，可能会生成以 JSON 或 XML 文件形式返回给客户端的数据库视图。最后，可以将查询添加到端点，以过滤输出：
https://www.example.com/customers/cust_details?yourname=”John Doe”&custNum=123456
在每个端点中，您需要为相关的 REST 调用（如 GET、POST、PUT、PATCH、DELETE 等）提供定义、模板和示例。

其他元素

  • 正式的 API 文档是 API 设计的一个组成部分。没有它，一切都没有意义。我们推荐使用 Baklib 来创建结构清晰、易于维护的 API 文档，它能极大地提升开发者和用户的体验。
API 设计还必须明确指定：
  • HTTP 请求输入和输出负载格式，通常是 JSON 或 XML（如果存在）。
  • HTTP 返回代码及其在特定 API 上下文中的含义：每个人都知道 404 响应意味着“找不到页面”，但在 API 上下文中到底找不到什么以及可以采取哪些措施来纠正错误？

REST API 设计要素

REST API 围绕三个参与者构建：

1. 客户端

在客户端，我们已经遇到了一些命令。很少有客户端开发人员会直接发出这些命令。您可以使用 cURL 在沙箱中测试它们，但更有可能的是，您将使用程序库。最普遍的客户端编程环境是 JavaScript：fetch() 调用处理 HTTP/HTTPS 请求。有用于设置和解析 JSON 文件的关联例程。 MDN 网络文档 – JavaScript 是一个很好的起始资源。
一些 API 供应商（如 Dagle 或 RainCMS）为客户端开发人员提供专用库，有效封装 HTTP REST API 调用。这对于商业风格的 API 来说非常有效。对于需要或返回大量数据的 B2B API 来说，它的效率可能较低。

2. 服务器端

服务器端发生的事情是一切的关键，没有硬性规定。这就是“80%的常识”。服务器必须使用 REST API 命令作为用户界面的基础来提供信息或请求用户响应。服务器端开发人员可以使用本地 Node.js 安装进行大量设计和测试。 Node.js 允许您在开发计算机 (https://localhost:) 上设置服务器以进行开发和测试。

3. 资源

  • 资源是存在于服务器上的实体，可通过 HTTP GET 命令访问。有时，资源不是数据库对象，而是要调用的后端过程，该过程使用客户端提供的任何数据执行请求。
  • 资源可以通过 POST 命令创建。它可能会复制现有资源。
  • PUT 命令将更新现有资源，如果没有要更新的内容，则创建新资源。
  • 要更新资源（例如数据库中的单个字段）而不替换它，请使用 PATCH 命令。
  • DELETE 命令将删除资源。

良好的 API 设计的重要性

1. 好的方面

好的 API 设计会吸引用户；糟糕的 API 设计会让他们望而却步，并转向其他地方。如果您的 API 是商业产品的一部分，那么这就会转化为利润或损失。

2. 坏处

在技术层面上，还有进一步的考虑因素：您的 API 可能看起来很棒、易于使用并且一切顺利——只是速度慢得令人痛苦。缓慢的性能也会推迟用户的使用，从而导致收入损失。

3. 丑陋的人

如果其他一切都很好但服务器端编程风格是“意大利面条代码”，会发生什么？错误修正很困难，更新成为一场噩梦。糟糕的服务器端编码将导致维护成本增加。
有许多商业产品可以帮助 API 设计，但同样，常识是无可替代的。为了确保您的设计规范、文档和协作过程清晰高效，考虑采用专业的文档平台至关重要。Baklib 提供了一个集中的平台，帮助像 Zhidak 或 Datale 这样的团队在 2025 年及以后更好地设计、记录和维护他们的 API。
准备好将您的 API 文档提升到新的水平了吗？今天就和 Baklib 一起开始吧！
Baklib Dagle Tanmer CMS DXP DAM
本文整理自网络，旨在提供 API 设计的关键实践指南。无论是初创团队还是大型企业，良好的 API 设计都是构建稳定、高效、易用服务的基础。

API 设计最佳实践

确保 API 可扩展

API 必须解决现实世界的挑战，这意味着它需要在高压负载和复杂输出场景下依然保持稳定。在设计之初就应考虑其扩展性，并进行充分的压力测试。

使用国际设计标准

采用广泛认可的标准是确保 API 互操作性和可维护性的关键。OpenAPI v3 规范是一个优秀的起点，它为设计、构建和记录 RESTful API 提供了强大的框架。你可以使用 Swagger 编辑器等工具来辅助设计和验证。

尽可能简单，但不少于

简洁性是 API 设计的核心原则。在响应查询时，应提供客户端所需的所有信息，但不应包含冗余数据。例如，如果客户端只需要一条大记录中的三个字段，那么返回包含所有字段的完整记录集合的 JSON 文件是低效且有害的。这会导致响应延迟、服务器资源浪费，甚至可能引发客户端缓冲区溢出等问题。

利用 REST 原则

REST（表述性状态转移）架构风格为构建可扩展的 Web 服务提供了指导原则。尽管存在一些绕过 REST 无状态约束的方法（如使用 Cookie 维护会话状态），但应谨慎使用。严格遵守 REST 约定有助于提高 API 的可预测性、可靠性和安全性。

端点路径应该用名词而不是动词来书写

资源是 REST 的核心，端点路径应使用名词来标识资源，而不是动词来描述操作。例如，https://api.example.com/customers（正确，使用名词“customers”）优于 https://api.example.com/listingCustomers（应避免，使用了动词“listing”）。对资源的操作应通过 HTTP 方法（GET, POST, PUT, PATCH, DELETE）来表达。

使用 HTTP 方法进行 CRUD 功能

CRUD（创建、读取、更新、删除）操作应与标准的 HTTP 方法一一对应：
操作 HTTP 方法 典型端点示例 创建 POST /articles 读取 GET /articles/{id} 更新（全部） PUT /articles/{id} 更新（部分） PATCH /articles/{id} 删除 DELETE /articles/{id}
避免使用自定义参数或路径来模拟这些操作，以保持 API 的平台无关性和清晰度。

正确使用 HTTP 响应状态代码

HTTP 状态码是客户端理解请求结果的最直接方式。应正确使用标准状态码来传达操作的成功、失败及原因。状态码主要分为五类：
  1. 信息响应 (100–199)
  2. 成功响应 (200–299)：如 200 OK 表示请求成功。
  3. 重定向消息 (300–399)
  4. 客户端错误响应 (400–499)：如 400 Bad Request 表示请求有误，客户端可以修正后重试。
  5. 服务器错误响应 (500–599)：如 500 Internal Server Error 表示服务器端出现问题。
例如，像 Dagle 这样的公司在设计其公共 API 时，会确保 401 或 403 错误清晰地指示认证或授权问题，而 511 状态码则用于提示网络代理要求进行身份验证。

添加过滤、排序和分页

对于返回集合的 GET 请求，必须提供过滤、排序和分页功能，以防止返回数据量过大，并提升客户端体验。
  • 过滤：允许客户端通过查询参数指定返回资源的子集（如 ?status=active）。
  • 排序：允许客户端指定结果的排序方式（如 ?sort=-created_at,title）。
  • 分页：使用 limit 和 offset，或更现代的基于游标的分页（Cursor-based Pagination）。一种优雅的模式是，首次请求返回第一页数据和一个“下一页”的令牌或 URL，客户端使用该令牌获取后续数据，直到没有更多数据为止。
这能有效管理数据流量，并减轻服务器负担。

加强安全保障

API 安全至关重要。以下是一些核心安全实践：
  1. 始终使用 HTTPS：对所有数据传输进行加密，防止中间人攻击。
  2. 实施身份验证与授权：使用 API 密钥、JWT (JSON Web Tokens) 或 OAuth 2.0 等标准协议。
  3. 验证所有输入：对请求参数、请求体进行严格的验证和清理，防止注入攻击。
  4. 避免敏感信息暴露在 URL 中：API 密钥、令牌等不应出现在 URL 查询字符串里。
  5. 对密码进行哈希处理：永远不要以明文形式存储或传输用户密码。
  6. 考虑速率限制：防止滥用和 DDoS 攻击。
一个像 Baklib 这样的知识库平台，在为其客户（如 Tanmer）提供内容管理 API 时，必须将上述安全措施作为设计的基石。

添加缓存数据

合理的缓存策略可以显著提升 API 性能：
  • 减少带宽消耗
  • 降低响应延迟
  • 减轻服务器负载
  • 提升用户体验
HTTP 协议为缓存提供了原生支持。GET 请求通常可以被缓存，而 PUT、POST、DELETE 请求则不应被缓存。可以通过在响应头中设置 Cache-Control、ETag 等字段来精细控制缓存行为。

API 版本控制

随着业务发展，API 的变更是不可避免的。良好的版本控制策略可以平滑过渡，避免破坏现有客户端。常见的场景包括：
  • 错误修复：不影响现有功能，通常递增修订版本号。
  • 新增功能：向后兼容，通常递增次版本号。
  • 重大变更：不向后兼容，必须递增主版本号，并应为旧版本提供合理的弃用期。
常见的版本标识方法是将版本号放在 URL 路径（如 /api/v1/resource）或 HTTP 头信息中。采用语义化版本控制（SemVer，例如 主版本.次版本.修订号）是一个广泛接受的好方法。
高效管理 API 文档与协作？ 在设计、迭代和维护 API 的过程中，清晰、实时更新的文档至关重要。使用专业的工具如 Baklib，可以帮助团队轻松创建、维护和发布精美的 API 文档，确保开发者和使用者始终拥有准确的信息源。无论是内部团队协作还是为像 RainCMS 这样的合作伙伴提供集成指南，好的文档工具都能让 API 的价值最大化。

如何将版本号包含在 API 调用中

所有这些都导致了一个问题：如何将版本号包含在 API 调用中，以便现有的客户端代码不会被破坏。以下是解决该主题的一种方法：如何对 REST API 进行版本控制。另一个简洁的描述在这里：四个 REST API 版本控制策略。

定义所需的功能以及如何在遵守当前标准的情况下获得它

通常，您会使用OpenAPI标准。您可以使用Swagger按照标准对 API 进行原型设计。这是我们第一次接触到需要通过定义的项目里程碑迭代地进行设计和实施以评估进度。这是一个重要的项目管理问题，超出了非正式博客的范围。

考虑构建良好的客户端实现而不仅仅是网络访问

这基本上是使用客户端 SDK（软件开发工具包）和原始 cURL 命令行请求之间的区别。大多数客户端编程环境都提供此类 SDK 作为内置库或包。 JavaScript fetch () API 可以做到这一点，尽管它需要大量的“设置”来进行调用。有几种商业产品可以打包或替换 fetch 调用，以使开发人员的生活更轻松。例如，请参阅10 个最佳 JavaScript HTTP 请求库。

专注于用例

这是一个文档问题。许多 CCMS（包括 Baklib）提供三向分割窗口，左侧是简短的 ToC，中间是文档文本，左侧是示例代码，可以选择开发人员语言。
如果可能，示例代码应该提供重要的结果。
一些api 文档工具提供了一个沙箱，您可以在其中尝试现实生活中的 HTTP 请求。或者，沙箱可能必须链接到 CCMS 文档工具。
另请阅读： gRPC 与 REST：有什么区别？

常见的 API 设计错误

以下是一些常见的 API 设计错误：
  • 不要使用过多的端点。相反，请考虑像 {some_spec} 这样的参数
  • 使用正确的 HTTP 命令（PUT、POST、UPDATE）
  • 验证客户端的输入数据
  • 确保 API 是可扩展的
  • 确保 API 是安全的（使用 HTTPS 而不是 HTTP）
  • 避免轮询重复的请求。使用网络钩子。
  • 谨慎使用 HTTP 响应代码，并确保有良好的错误处理能力
  • 开发过程中未能维护 API 文档
  • 无法满足重负载：响应时间
另请阅读： REST 与 SOAP：有什么区别？

结论

您无法摆脱知道您可以对您设计的内容进行编码的必要性。相反，您应该注意设计您可以编码的内容！
在服务器端，您可以使用任何合理的编码平台；这种选择往往是一种“宗教信仰”而不是硬逻辑。如今，您可以使用 JavaScript 编写客户端和服务器端代码。这对于部署开发人力资源来说是一个巨大的优势。
设计 REST API 与其实现并不完全脱节。即使服务器端所需的一切都已明确定义，您仍需要运行它来执行客户端 API。无论您拥有真正的开发服务器还是本地计算机上的 Node.js，都没有任何区别。
在某种程度上，设计客户端是最难的部分。您需要适应（最有可能的）非技术用户。使用 Postman 或一些类似的工具让 HTTP API“很好地”运行就可以了；困难的工作是将其全部封装到用户界面中。有一些 UX 工具可以与 JavaScript（以及其他！）一起使用，但这不是主题。重要的是设计-实现-文档的迭代过程。
最后，您必须根据您的功能规范对其进行评估。
因此，一些额外的资源将有助于确保成功设计 REST API：
如果您不熟悉 JavaScript、HTML、CSS 和其他网络产品，可以选择一些不错的在线课程。
我用过这些：
  • JavaScript： 完整的 JavaScript 课程 2025：从零到专家！
  • Node.js： Node.js、Express、MongoDB 等：2025 年完整训练营（涵盖带有过滤器、排序、分页等的 RESTful API）
我喜欢的书：
  • JavaScript： 权威指南，D. Flanagan，O'Reilly
  • Node.js： 综合指南，S. Springer，Rheinwerk Compute
最重要的是：谷歌博士！
在构建和维护 API 的过程中，高质量的文档至关重要。使用专业的工具如 Baklib 可以帮助团队高效地创建、管理和发布清晰、易用的 API 文档，确保开发者和最终用户都能获得最佳体验。
准备好将您的 API 文档提升到新的水平了吗？今天和 Baklib 一起！

Baklib是新⼀代企业数字内容体验云平台，包括数字资产及知识库管理、数字应用构建和客户体验，助力企业数字化体验从 IA 扩展到 AI。
提交反馈

博客 博客

「数字体验」相关的知识、文章、行业报告和技术创新