创建更好的静态应用程序接口的 7 个技巧

罗伯特-斯菲奇（Robert Sfichi），2021 年 6 月 2 日

构建安全、易用的 RESTful API 是令开发人员头疼不已的任务之一。长期以来，REST API 一直是促进后端和前端应用程序之间通信的行业标准。

我们的团队深知设计良好的应用程序接口（API）的重要性，并收集了最佳实践来帮助开发人员构建完美的 REST API。

让我们通过最重要的细节与您分享一切！

如何创建更好的 REST API 的技巧

开发人员在尝试构建 REST API 时最容易犯的一些错误有

• 文件编写不当
• 未定义的架构
• 端点定义不一致
• 沟通不畅
• 安全措施薄弱

我们生活的世界并不完美。犯错误是正常的。但是，在参与任何项目之前，您必须采取一切预防措施，并了解您可能犯下的所有风险或错误。

同样的方法也适用于我们的案例。因此，我们的团队将在以下段落中根据他们的个人和专业经验为您提供一些建议。

1.认真对待文件

记录 API 可以帮助您和您的团队更好地理解应用程序的数据流。在构建应用程序接口时，难免会出现问题。库更新、应用程序接口版本或安全问题都会让你希望自己已经编写了文档。

通过这样的管理，您还可以减少新的远程或内部软件开发人员入职所需的资源，并提高团队更新和维护操作的便捷性。尽量让他们在不完全了解您所使用的技术的情况下，也能在您的应用程序接口之上进行构建。

值得庆幸的是，如今创建文档要容易得多。Apiary、Swagger、Raml等工具可以帮助开发人员即时生成文档。你还可以随时从实用的、写得很好的文档中汲取灵感，如The Rust Docs、GitHub Developer Docs、Ruby On Rails Guides、CasperJS 或Moment.js。

2.注重安全

我们应始终努力保持客户端与服务器之间的通信私密性。

开发人员使用应用程序接口来构建服务和传输数据。如果一个应用程序接口被破坏、暴露或有重大数据泄露，肯定不会被任何开发者选择。

尝试从一开始就验证请求参数。实施验证检查，并阻止每个未通过特定验证的请求。对输入类型、格式和长度进行验证。只接受特定端点的特定 HTTP 方法，并在请求中包含时间戳，这样只有在特定时间范围内发出的请求才会被接受。这样可以防止一些可能会攻击服务器的暴力攻击。

通过实施 OAuth 2.0 身份验证框架，您可以进一步提高身份验证的安全性。在第三方应用程序的帮助下，您可以为用户创建一个更安全的环境。

切勿在 URL 中暴露用户名、密码、API 密钥等敏感信息。如果您确实需要通过在 URL 中存储这些信息来传输这些信息，请将其序列化，只有需要与之通信的机器才能理解接收到的数据。

3.选择适当的数据格式以支持

应用程序接口就像是服务器和客户端之间的桥梁。因此，我们应以适合双方的格式传输数据。这种选择将影响请求的速度和成功率。

在构建应用程序接口时，最常用的数据格式包括直接数据、馈送数据和数据库数据格式。

在尝试与其他应用程序接口交互时，直接数据格式是最佳选择。最常用的格式有 JSON、YAML 和 XML。

反馈数据格式通常用于发布来自服务器或前端网络应用程序的更新，并通知用户已作出的更改。您可能已经猜到，这些格式最常用于社交媒体、博客或视频共享平台。

在大多数情况下，数据库数据格式用于处理不同数据库之间或其他应用程序与数据库之间的数据。SQL 和 CSV 是这类格式中最常用的两种。

4.使用分页

如果您和您的团队正在构建的应用程序接口将返回大量数据，那么实施分页可能是个好主意。我们应始终避免出现用户有可能导致服务瘫痪的任何情况。

我们建议对返回的数据使用默认限制以及limit 和offset 等参数，就像这样：/users?limit=30&offset=60。

分页还能帮助用户消除决策疲劳，并消除已被鄙视的无限滚动。

5.为每个主要功能创建版本

应用程序接口的版本化过程有助于开发人员保持对应用程序的控制。你永远不可能知道新的更新会如何影响每个用户的可用性。即使你彻底改变了 API，也要尽量保留旧版本的 API 备份。

让我们举例说明如何对应用程序接口进行版本控制：

• 将版本号直接放在 API 的 URL 中：api.example.com/v1/users
• 设置自定义标头以包含API的版本号：curl -H "API-version: 1.0" https://api.example.com/users
• 调整接受头以包含API的版本号：curl -H "Accept: application/vnd.example.v1+json" https://api.example.com/users
• 添加版本号作为查询参数： https://api.example.com/users?version=1

6.使用正确的 HTTP 方法和代码

RESTful API 有四种方法来说明开发人员将如何处理传递的数据。

虽然这似乎是合乎逻辑的做法，但开发人员往往只使用以下介绍的两种 HTTP 方法。在需要的情况下，使用每一种方法都是一种完美的做法。

• GET- 每次需要获取资源或资源集合时，请使用此方法。
• POST- 开发人员应在每次需要创建新资源或资源集合时使用它。
• PUT- 这种方法用于更新特定信息。
• DELETE- 不言自明。它可以帮助我们删除现有资源或资源集合。

就像开发人员只喜欢使用前面提到的两种 HTTP 代码一样，大多数情况下，他们也只使用两种 HTTP 代码。这可能会给未来的自己和将来参与项目的所有开发人员带来很多麻烦。

• 200 OK- 作为开发人员，这是最常见的代码。至少我们希望如此。每当操作成功执行时，它就会出现在我们面前。
• 201 CREATED- 前面介绍的 POST 方法与此 HTTP 代码相辅相成，因为它应该提醒客户端已成功创建了资源。
• 400 BAD REQUEST（400 错误请求）--这是在请求未成功执行时出现的 HTTP 代码。
• 401 UNAUTHORIZED（未授权）--如果我们需要限制用户访问应用程序的某个部分，则应将此 HTTP 代码与错误信息一起发送。
• 404 NOT FOUND- 整个互联网上最常见的 HTTP 代码。即使没有学过软件开发的人也知道 404 HTTP 代码意味着资源未找到。
• 500 INTERNAL SERVER ERROR（内部服务器错误）- 当服务器无法响应时，应返回此错误。

正如您所看到的，所有 HTTP 代码都不言自明。在需要的情况下使用每一个代码，从长远来看都能帮助节省大量时间。

7.确保错误信息清晰

我们都知道，当我们遇到错误，而错误信息又含糊不清时，是多么令人沮丧。不仅服务无法运行，而且我们现在还必须找到问题的根源。

我们必须抛出正确的错误信息和最明确的 HTTP 错误代码，以消除这种混淆。

例如，如果用户想创建一个新账户，但该电子邮件已在平台上使用，我们应返回一个带有 "电子邮件已存在 "信息的 400 HTTP 代码。这样，我们就可以避免处理大量请求，因为用户会知道问题所在，也不会强制注册。

那么，有效的 REST API 是什么样的呢？

在此，我们将为您提供一份完整的提示清单。这些只是你可以用来创建更安全的 REST API 的部分方法。当然，还有更多的方法，但如果你只使用上面介绍的方法，你可能会领先于大多数已构建的方法。

但是，如果您没有时间和耐心为您的网络搜刮项目构建 API，为什么不投资于现成的东西呢？我们的团队致力于创建最安全、最易用的网络搜刮 API。这些只是他们用来确保不会出现任何数据泄露或 API 停机的一些主要原则。

如果你想试一试，创建一个免费账户并测试最成功的网络搜索 API 之一，就能获得 1000 次 API 调用。

现在就开始您的网络搜索之旅！