在开始 REST API 设计之前，您需要一个功能规范。它规定了系统做什么，而不是如何做。它可能包括一些模型屏幕截图和信息流程图，但它本质上是一个高级文档。相比之下，API 设计深入了解了其工作原理的本质。

快速概览

网络上有无数提倡“API 设计”、“最佳实践”等的网站和页面。
API 设计大约 80% 是常识，其余的是技术性的。

Web API 向客户端用户公开服务器数据并接受他们返回的请求。大多数消费者网络流量是按请求提供给客户端的数据。相反，客户提供登录数据、进行购买、填写政府表格等。

在服务器上，信息通常存储在 MySQL 等数据库中。客户端API封装了数据库上的活动，例如下载信息、存储新客户端信息以及更改客户端信息。

基本思想是按反映主要数据库表的主要数据类别来拆分 API。尽管客户端 API 请求会转换为服务器上的数据库操作，但 API 客户端对底层数据库一无所知。

例如，商业零售网站将拥有有关客户、产品、制造商等的数据。访问亚马逊等网站来了解这个想法。

在 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 设计的一个组成部分。没有它，一切都没有意义。

API 设计还必须明确指定：

• * * HTTP 请求输入和输出负载格式，通常是 JSON 或 XML（如果存在）。 * HTTP 返回代码及其在特定 API 上下文中的含义：每个人都知道 404 响应意味着“找不到页面”，但在 API 上下文中到底找不到什么以及可以采取哪些措施来纠正错误？

REST API 设计要素

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

1. 客户端

在客户端，我们已经遇到了一些命令。很少有客户端开发人员会直接发出这些命令。您可以使用 cURL 在沙箱中测试它们，但更有可能的是，您将使用程序库。最普遍的客户端编程环境是 JavaScript：fetch() 调用处理 HTTP/HTTPS 请求。有用于设置和解析 JSON 文件的关联例程。 MDN 网络文档 – JavaScript 是一个很好的起始资源。

一些 API 供应商为客户端开发人员提供专用库，有效封装 HTTP REST API 调用。这对于我们都知道的商业风格的 API 来说非常有效。对于需要或返回大量数据的 B2B API 来说，它的效率可能较低。

2、服务器端

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

3. 资源

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

良好的 API 设计的重要性

1. 好的方面

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

2. 坏处

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

3. 丑陋的人

如果其他一切都很好但服务器端编程风格是“意大利面条代码”，会发生什么？错误修正很困难，更新成为一场噩梦。糟糕的服务器端编码将导致维护成本增加。

有许多商业产品可以帮助 API 设计，但同样，常识是无可替代的。

准备好将您的 API 文档提升到新的水平了吗？今天和baklib一起！

API设计最佳实践

确保 API 可扩展

API 必须解决现实世界的挑战：在负载和过长的输出下进行测试。

使用国际设计标准

OpenAPI v3 规范是一个好的开始。请查看此处， OpenAPI 规范以及此处： Swagger 编辑器。

尽可能简单，但不少于

这是一个样式问题，但它可能会影响性能：响应查询时，提供所需的所有信息，但不再提供更多信息。如果您需要在一条大记录中提供三个字段，那么包含这些字段的所有记录的 JSON 文件就显得有些过头了，甚至会适得其反。它会减慢响应速度，甚至可能造成瓶颈情况。它还可能导致客户端缓冲区溢出。

利用休息

有一些“设备”可以绕过 REST，最常见的是维护状态的方法。其中最著名的是 cookie。它们占有一席之地，大多数站点都使用它们，通常为每个请求提供会话用户凭据。超出 REST 约定甚至可能会带来安全风险。

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

此端点https://www.example.com/customers使用名词 – 客户。应避免使用下一种示例https://www.example.com/listingCustomers 。 REST API 中唯一的动词是 GET、POST、PUT、PATCH、DELETE 等命令。

使用 HTTP 方法进行 CRUD 功能

首字母缩略词 CRUD 代表创建、读取、更新和删除。应使用相应的 HTTP 方法，而不是使用“智能”编程技巧绕过。无需通过HTTP即可访问远程数据库；不是吗，它不是平台无关的。

与 HTTP 响应状态代码一起使用

HTTP 响应状态代码记录在此处： HTTP 响应状态代码。

HTTP 响应状态代码指示特定HTTP请求是否已成功完成。响应分为五类：

1. 1.信息性答复(100 – 199)
1. 成功回复(200 – 299)
2. 重定向消息(300 – 399)
3. 客户端错误响应(400 – 499)
4. 服务器错误响应(500 – 599)

在许多情况下，我们需要 200 响应来表示成功。 400 响应通常可以在客户端进行更正并重新提交请求。 500 个响应可能需要“稍后返回”操作。例外情况是 511，由控制服务器访问的代理发出的“需要网络身份验证” 。这意味着客户端凭据不正确。

添加过滤、排序和分页

在 GET 查询中，这三个查询都是通过在端点后添加参数来完成的。没有标准方法，很大程度上取决于后端开发人员。请参阅REST API 设计：过滤、排序和分页。

一种有趣的分页方法基于以下范例：

1. 1. 通过 GET 查询，提供所需的页面长度（以行为单位）。
1. GET 返回数据的第一页和一个特殊的继续 URL，所有这些都在 JSON 文件中。
2. 请使用继续 URL 重复 GET，直到没有更多数据为止。

加强安全保障

强制使用 HTTPS 进行数据传输，而不是 HTTP。这是一个很大的主题，远远超出了简短博客的范围。作为起点，请查看此处：内容安全策略 (CSP) ，此处： REST API 安全性的最佳实践：身份验证和授权，以及此处： REST API 安全要点

从最后一个链接，我们有一个快速清单：

1. 1. 1. 保持简单。保护 API/系统 – 它需要有多安全。 2. 始终使用 HTTPS。始终使用 SSL。 3. 使用密码哈希。始终对密码进行加密。切勿以明文形式发送它们。 4. 切勿在 URL 上暴露敏感信息。用户名、密码、会话令牌和 API 密钥不应出现在 URL 中，因为这可以在 Web 服务器日志中捕获，这使得它们很容易被利用。 5.考虑使用OAuth进行授权。 6. 考虑在每个请求中添加时间戳。在自定义 HTTP 标头中执行此操作。
   输入参数验证。我们上面提到过这一点。如果参数验证失败，则拒绝请求。

添加缓存数据

缓存存储经常访问的数据的副本。缓存响应数据可以

• * * 减少带宽使用 * 减少响应延迟 * 减少服务器负载 * 暂时隐藏网络故障

GET 请求会自动缓存。 PUT 和 DELETE 不是。

可以使用请求中的缓存控制标头来控制缓存。请参阅此处有关缓存的教程：缓存 REST API 响应。

API版本控制

这些场景需要版本控制：

• * * 错误修正 * 添加新功能 * 全新版本

典型的版本控制方案基于三位数代码：

<主要版本>.<次要版本>.<维护构建级别>

错误修正不得对 API 进行任何更改。它对 API 用户是透明的。它增加了维护构建级别。

添加新功能可能不会以任何方式改变现有的 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 文档工具。

常见的 API 设计错误

以下是一些常见的 API 设计错误：

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

结论

您无法摆脱知道您可以对您设计的内容进行编码的必要性。相反，您应该注意设计您可以编码的内容！

在服务器端，您可以使用任何合理的编码平台；这种选择往往是一种“宗教信仰”而不是硬逻辑。如今，您可以使用 JavaScript 编写客户端和服务器端代码。这对于部署开发人力资源来说是一个巨大的优势。

设计 REST API 与其实现并不完全脱节。即使服务器端所需的一切都已明确定义，您仍需要运行它来执行客户端 API。无论您拥有真正的开发服务器还是本地计算机上的 Node.js，都没有任何区别。

在某种程度上，设计客户端是最难的部分。您需要适应（最有可能的）非技术用户。使用 Postman 或一些类似的工具让 HTTP API“很好地”运行就可以了；困难的工作是将其全部封装到用户界面中。有一些 UX 工具可以与 JavaScript（以及其他！）一起使用，但这不是主题。重要的是设计-实现-文档的迭代过程。

最后，您必须根据您的功能规范对其进行评估。
因此，一些额外的资源将有助于确保成功设计 REST API：

如果您不熟悉 JavaScript、HTML、CSS 和其他网络产品，可以选择一些不错的在线课程。

我用过这些：

• ** JavaScript：完整的 JavaScript 课程 2023：从零到专家！ * Node.js： Node.js、Express、MongoDB 等：2023 年完整训练营
  （涵盖带有过滤器、排序、分页等的 RESTful API）

我喜欢的书：

• ** JavaScript：权威指南，D. Flanagan，O'Reilly * Node.js：综合指南，S. Springer，Rheinwerk Compute

最重要的是：谷歌博士！

准备好将您的 API 文档提升到新的水平了吗？今天和baklib一起！