REST API 是当今可用的最常见的 Web 服务类型之一 。它们允许包括浏览器应用程序在内的各种客户端通过 REST API 与服务器通信 。因此，正确设计 REST API 非常重要，这样我们以后就不会遇到问题 。我们必须考虑 API 使用者的安全性、性能和易用性 。
否则，我们会为使用我们 API 的客户制造问题，这不愉快并且会影响人们使用我们的 API 。如果我们不遵循普遍接受的约定，那么我们就会混淆 API 的维护者和使用它们的客户端，因为它与每个人的期望不同 。
在本文中，我们将研究如何设计 REST API，使其对任何使用它们的人都易于理解、面向未来、安全且快速，因为它们向可能是机密的客户端提供数据 。
- 接受并使用 JSON 响应
- 在端点路径中使用名词而不是动词
- 用复数名词命名集合
- 分层对象的嵌套资源
- 优雅地处理错误并返回标准错误代码
- 允许过滤、排序和分页
- 保持良好的安全实践
- 缓存数据以提高性能
- 版本控制我们的 API
注意：对于通过 Internet 调用的 REST API，您需要遵循REST API 身份验证的最佳实践 。
接受并使用 JSON 响应REST API 应该接受 JSON 作为请求负载，并发送响应到 JSON 。JSON 是传输数据的标准 。几乎所有联网技术都可以使用它：JAVAScript 具有通过 Fetch API 或其他 HTTP 客户端对 JSON 进行编码和解码的内置方法 。服务器端技术具有无需做太多工作即可解码 JSON 的库 。
还有其他方法可以传输数据 。如果不将数据自己转换为可以使用的东西（通常是 JSON），框架就不会广泛支持 XML 。我们无法在客户端轻松操作这些数据，尤其是在浏览器中 。只是为了进行正常的数据传输，最终需要做很多额外的工作 。
表单数据有利于发送数据，特别是如果我们要发送文件 。但是对于文本和数字，我们不需要表单数据来传输它们，因为对于大多数框架，我们可以通过直接在客户端获取数据来传输 JSON 。这是迄今为止最直接的做法 。
为确保当我们的 REST API 应用程序使用 JSON 响应时客户端将其解释为这样，我们应该Content-Type在响应标头中设置为Application/json在发出请求之后 。许多服务器端应用程序框架会自动设置响应标头 。一些 HTTP 客户端查看Content-Type响应标头并根据该格式解析数据 。
【Rest API 最佳设计实践】唯一的例外是如果我们尝试在客户端和服务器之间发送和接收文件 。然后我们需要处理文件响应并将表单数据从客户端发送到服务器 。但这是另一个话题 。
我们还应该确保我们的端点返回 JSON 作为响应 。许多服务器端框架将此作为内置功能 。
让我们看一个接受 JSON 有效负载的示例 API 。此示例将使用Node.js的Express后端框架 。我们可以使用body-parser中间件来解析 JSON 请求体，然后我们可以res.json使用我们想要作为 JSON 响应返回的对象调用该方法，如下所示：
const express = require('express');const bodyParser = require('body-parser');const app = express();app.use(bodyParser.json());app.post('/', (req, res) => { res.json(req.body);});app.listen(3000, () => console.log('server started'));bodyParser.json()将 JSON 请求正文字符串解析为 JavaScript 对象，然后将其分配给该req.body对象 。将Content-Type响应中的标头设置为application/json; charset=utf-8不做任何更改 。上述方法适用于大多数其他后端框架 。
在端点路径中使用名词而不是动词我们不应该在端点路径中使用动词 。相反，我们应该使用代表我们正在检索或操作的端点的实体的名词作为路径名 。
这是因为我们的 HTTP 请求方法已经有了动词 。在我们的 API 端点路径中包含动词没有用处，而且由于它没有传达任何新信息，它会导致不必要的冗长 。选择的动词可能会因开发人员的突发奇想而有所不同 。例如，有些喜欢“get”，有些喜欢“retrieve”，所以最好让 HTTP GET 动词告诉我们端点做什么 。
该操作应由我们正在制作的 HTTP 请求方法指示 。最常见的方法包括 GET、POST、PUT 和 DELETE 。
