打造更优质 REST API 的 7 个技巧

开发者在构建 REST API 时常犯的错误包括：

• 文档编写不佳
• 架构定义不明确
• 端点定义不一致
• 沟通不畅
• 安全措施薄弱

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

本案例亦遵循这一原则。因此，在接下来的段落中，我们的团队将基于个人及专业经验，为您提供几条建议。

编写 API 文档有助于您和团队更好地理解应用程序的数据流。在构建 API 时，问题在所难免。诸如库更新、API 版本控制或安全问题等情况，都会让您后悔当初没有编写文档。

通过妥善管理文档，您不仅能减少培训新入职远程或内部软件开发人员的资源消耗，还能让团队更轻松地进行更新和维护。即使开发人员尚未完全理解您所使用的技术，也要让他们能够基于您的 API 进行开发。

值得庆幸的是，如今编写文档已变得轻松许多。Apiary、Swagger、Raml 等众多工具能帮助开发者瞬间生成文档。你还可以参考一些实用且撰写精良的文档，例如 Rust 文档、GitHub 开发者文档、Ruby on Rails 指南、CasperJS 或 Moment.js。

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

开发者利用 API 构建服务并传输数据。如果某个 API 存在故障、暴露在外或发生重大数据泄露，任何开发者都不会选择它。

请从一开始就对请求参数进行验证。实现验证机制，并拦截所有未通过特定验证的请求。包含对输入类型、格式和长度的验证。仅接受特定端点的特定 HTTP 方法，并在请求中加入时间戳，确保仅接受在特定时间段内发出的请求。这可以防止某些可能针对您服务器的暴力破解攻击。

通过实施 OAuth 2.0 认证框架，您可以进一步提升身份验证的安全性。借助第三方应用，您可以为用户创建更安全的环境。

切勿在 URL 中暴露用户名、密码、API 密钥等敏感信息。若确实需要通过 URL 传输此类信息，请采用序列化处理，确保仅目标通信设备能解析接收到的数据。

API 就像是服务器与客户端之间的桥梁。因此，我们应采用双方都适用的格式传输数据。这一选择将直接影响请求的速度和成功率。

构建 API 时最常用的数据格式包括直接数据、源数据和数据库数据格式。

当需要与其他 API 交互时，直接数据格式是最佳选择。其中最常用的包括 JSON、YAML 和 XML。

源数据格式通常用于发布来自服务器或前端 Web 应用程序的更新，并通知用户这些更改已生效。正如您可能已经猜到的，这些格式最常用于社交媒体、博客或视频分享平台。

在大多数情况下，数据库数据格式用于在不同数据库之间，或应用程序与数据库之间进行数据操作。SQL和CSV是该类别中使用最频繁的两种格式。

如果您和您的团队正在构建的 API 将返回大量数据，实现分页可能是个好主意。我们应始终避免任何可能导致用户有机会导致服务崩溃的情况。

我们建议为返回的数据设置默认限制，并使用 limit 和 offset 等参数，例如：/users?limit=30&offset=60。

分页功能还能有效缓解用户的决策疲劳，并彻底告别备受诟病的无限滚动。

对 API 进行版本控制有助于开发者保持对应用程序的掌控。您永远无法预知新更新会对每位用户的可用性产生何种影响。即使您对 API 进行了彻底改版，也应始终保留旧版本的备份。

下面我们来看一些 API 版本化的示例：

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

RESTful API 提供了四种方法来表明开发者将如何处理传入的数据。

尽管这看似合乎逻辑，但开发者往往只使用以下列出的 HTTP 方法中的两种。在需要时灵活运用每一种方法才是最佳实践。

• GET — 每次需要获取资源或资源集合时，请使用此方法。
• POST — 每次需要创建新资源或资源集合时，开发者都应使用此方法。
• PUT — 该方法用于更新特定信息。
• DELETE — 其含义不言自明。它用于删除现有资源或资源集合。

正如开发者倾向于仅使用前述的两种 HTTP 状态码一样，大多数时候他们确实只使用其中两种。这种做法不仅会给未来的自己带来诸多困扰，也会给未来参与该项目开发的全体开发者造成麻烦。

• 200 OK —— 这是我们作为开发者最常遇到的状态码。或者说，至少我们希望如此。每当操作成功执行时，系统都会返回此状态码。
• 201 CREATED — 此前介绍的 POST 方法与该 HTTP 状态码密不可分，因为它旨在告知客户端资源已成功创建。
• 400 BAD REQUEST — 这是请求未成功时出现的 HTTP 状态码。
• 401 未授权 —— 若需限制用户访问应用程序的某些部分，应将此 HTTP 状态码与错误信息一同返回。
• 404 未找到 —— 这是整个互联网上最常见的 HTTP 状态码。即使没有学习过软件开发的人也知道，404 状态码意味着资源未被找到。
• 500 内部服务器错误 — 每当服务器无法响应时，都应返回此错误。

如您所见，所有 HTTP 状态码都相当直观。在适当的情况下使用它们，从长远来看能节省大量时间。

我们都知道，当遇到错误却收到模棱两可的提示时，那种沮丧感是多么强烈。不仅服务无法正常运行，我们还得费力去排查问题根源。

我们必须返回正确的错误信息和最明确的 HTTP 错误代码，以消除这种困惑。

例如，如果用户想要创建新账户，但该邮箱在平台上已被使用，我们应返回 400 HTTP 状态码并显示“邮箱已存在”的提示。这样一来，由于用户清楚问题所在，便不会强行注册，从而避免了大量重复请求。

至此，我们已完整列举了所有建议。这些仅仅是构建更安全 REST API 的部分方法。当然，还有许多其他方法，但即使仅采用上述方法，您的 API 性能也极有可能超越大多数现有的 API。

不过，如果您没有时间和耐心为自己的网络爬虫项目构建 API，何不投资于现成的解决方案？我们的团队倾力打造了最安全且易于使用的网络爬虫 API 之一。以下正是他们为确保绝不发生数据泄露或 API 停机而遵循的核心原则。

若您想尝试一下，只需注册一个免费账户，即可获得 1000 次 API 调用额度，亲身体验这款最成功的网页抓取 API 之一。

立即开启您的网页抓取之旅！