API开发指南：REST、GraphQL、gRPC

不同行业的公司使用 API 来实现其应用程序的客户端和服务器端之间的通信，与第三方软件集成，并允许外部应用程序访问其系统。此外，构建自定义 API 并使其货币化可以成为业务发展战略的重要组成部分。

如果 API 在您的项目中发挥着至关重要的作用，那么对其开发的要求可能会很严格。您需要知道如何应对技术挑战、选择什么协议以及应用哪些实践来构建一流的以 API 为中心的产品。以下指南旨在回答这些问题。

API 协议：类型和开发细节

让我们首先探索不同类型的 API 及其开发功能，以便您可以找到最适合您的项目的协议。无论您选择哪种编程语言进行 API 开发， Node.js 、Python、Ruby 还是其他语言，协议的类型都更为重要。目前，自定义 API 开发的主要方法是 REST、GraphQL 和 gRPC。

休息API

REST，也称为表述性状态传输，是指无状态的 API，这意味着每个请求都包含完成它所需的所有详细信息。绝大多数后端开发人员熟悉 REST API 开发。这是最常用和通用的 API 类型，在大量软件项目中使用。作为一个进入门槛较低的简单协议，REST API 不太可能面临未来的支持问题。

通过 REST，我们可以清楚地了解我们请求的内容和方式，并且我们知道期望得到什么响应。这同样适用于错误；我们可以在任何给定时刻根据状态代码查明错误。我们还可以使用自定义元素升级此协议，以使客户端更容易理解错误。

REST 的优点：简单、速度快、客户端和服务器之间的关系清晰、易于缓存响应以及内置安全功能。

缺点：由于服务器的标准化响应而缺乏灵活性。例如，假设我们有一份公司经理列表，在一页上，我们可能希望包含带有角色和联系方式的姓名，而在另一页上，只有姓名，没有任何其他数据。在 REST 场景中，我们要么必须在任何地方都使用一个请求，以不必要的数据进行响应并耗尽带宽，要么为每个页面编写一个单独的请求，从而导致代码重复和复杂性。通常，自始至终都使用相同的请求。

图形查询接口

GraphQL 是 Facebook 开发的 API 查询语言。 GraphQL 比 REST API 更灵活，让开发人员可以在单个请求（客户端驱动的查询）中获取所有需要的数据。开发人员还可以指定他们希望从 API 接收的数据类型。

GraphQL 解决了请求-响应交互的问题。我们利用特定的查询语言来指示服务器在任何给定时刻客户端的特定数据需求。回顾经理的示例，客户端默认不接收标准化数据，但可以选择所需的信息（如姓名和电话号码），并且服务器会使用此特定信息进行响应。

该系统非常适合需要更大灵活性和可扩展性、复杂系统和微服务的应用程序。

GraphQL 的优点：这种方法可以节省带宽并提高性能，提供更大的灵活性和可扩展性。

缺点：查询语言更复杂，进入门槛相当高，如果缺乏专家，支持可能会变得复杂。社区也更小。

通用RPC接口

gRPC是Google创建的开源RPC框架，被认为是一种高性能的API开发技术。 gRPC 利用 Protocol Buffers，这是一种与语言无关、平台中立的机制，用于序列化结构化数据。

与非常相似的 REST 和 GraphQL 不同，gRPC 提供不同的客户端-服务器交互，并且只能与 HTTP/2.0 协议一起使用。这种先进的协议在数据压缩、用户连接等方面提供了优势。

gRPC 非常适合具有高性能通信要求的项目。

优点：gRPC 通过流及其查询语言与服务器进行通信，使整个过程看起来就像发生在单个系统中一样，无论您是在前端还是后端。前端可以调用后端编写的方法。然而，实际上，您需要先编写服务器方法并构建它们，然后前端才知道这些方法存在并可以使用。设置所有这些都需要具有此类 API 的经验。

其他优点包括更紧凑的数据、更好的性能和快速响应。

缺点包括社区较小（协议仍在发展中）和相对较高的进入门槛。了解数据传输协议也很重要；每个新人都可能不熟悉该协议，需要接受培训。与其他 API 开发方法相比，这种方法相当复杂并且需要更多时间，这对于项目来说并不总是合理的。

API 解决方案的主要特性

在API开发的启动和进展过程中，软件工程师应该考虑几个关键点。这将确保您的 API 的安全性和效率。

认证和授权

身份验证验证正确的身份，而授权确定经过验证的用户是否可以执行特定操作。 JWT、OAuth 和 OAuth2 等常见规范可处理这些任务。

身份验证方法的选择取决于所需的安全级别与易于实施和维护之间的平衡。 OAuth提供了可扩展性和出色的用户体验，但需要更多的实施和维护工作。 OpenID 可以通过授权服务器验证客户端的身份和配置文件来补充 OAuth。

查询、过滤、排序和分页

随着数据库的增长，数据检索可能会变得更慢。为了缓解这种情况，请实施缓存、分页、排序和过滤。

排序根据特定条件组织数据，而分页则决定显示多少数据以及何时显示。这些功能可提高处理时间、响应时间和安全性。

API 中的过滤可根据特定条件缩小结果集范围，从而提高 API 性能并减少网络数据传输。您可以根据 API 类型以不同的方式实现排序、过滤和分页（例如，使用 REST API 中的路径参数）。

缓存以提高性能

缓存将频繁请求的数据存储在辅助存储中，从而减少对主数据库的调用。该策略提高了数据检索速度并降低了请求成本。 Memcached 和 Redis 等工具可以帮助完成此过程。

根据存储缓存的位置，您可以使用客户端缓存或服务器缓存。客户端缓存通过在本地存储例行请求来提高客户端和服务器的效率，而服务器缓存则通过在缓存中存储重复的调用来减少服务器负载。

REST 提供更简单的缓存机制。使用 GraphQL API 和 gRPC API，开发人员必须在缓存上花费更多时间。

错误处理

有效的错误处理通过区分客户端和服务器错误来简化调试。提供清晰的错误代码、指定错误数量、解释错误原因以及区分一般错误和领域错误是有效的错误处理实践。

验证

验证确认数据的正确性。客户端验证通常涉及及时反馈纠正，这对产品来说是一个优点，而服务器端验证是确保安全性、数据完整性和漏洞保护的必备条件。它包括验证所需属性或定义属性类型等任务。

自定义 API 开发的最佳实践

API 开发的一些最佳实践将帮助您避免众所周知的错误并提高产品的性能、安全性和可扩展性。但值得注意的是，每个案例都是独一无二的，可能需要量身定制的创新解决方案。

返回标准错误代码

优雅地处理错误以避免 API 用户感到困惑至关重要。当发生错误时，返回指示特定错误类型的适当 HTTP 响应代码，为 API 维护提供有价值的信息。如果不处理错误可能会破坏系统，因此最好立即处理它们。

错误代码必须附有信息性消息，以帮助维护人员有效地解决问题。然而，确保这些错误消息不会暴露攻击者可能利用的敏感信息来执行恶意活动（例如数据盗窃或系统中断）至关重要。

导航 API 版本控制

为了确保平稳过渡并避免干扰客户端，每当进行任何更改时都必须使用不同版本的 API。版本控制可以使用语义版本控制来完成，例如 2.0.6（表示主要版本 2 和第六个补丁），这是现代应用程序中的常见做法。

这种方法使我们能够逐步淘汰旧的端点，而不是要求每个人同时迁移到新的 API。例如，v1 端点可以为不想更改的用户保持活动状态，而 v2 则以其令人兴奋的新功能迎合那些准备升级的用户。当您的 API 公开时，这一点变得尤其重要，因为版本控制可确保与依赖您的 API 的第三方应用程序的兼容性。

通过实施版本控制，Web API 可以清楚地指示其提供的功能和资源，并且客户端应用程序可以针对这些功能或资源的特定版本发出请求。

为 API 制作准确的文档

API 文档向开发人员介绍如何使用 API 以及从哪里开始。这对于集成 API 的开发人员和软件现代化的团队来说都是必要的。

如果您的 API 被详细记录，则可以更轻松地提高 API 的认知度和采用率，并减少远程和内部开发人员的培训时间和成本。同时，任何内部团队都可以利用 API 文档来了解应用的方法、资源、请求和响应，这将简化维护和更新。

您需要提供简洁的教程来帮助开发人员快速入门，创建一个全面的术语表定义API术语，并确保以用户友好的方式解释资源和方法。列出所有项目术语，以统一最终用户（开发人员）的理解，使他们即使技术知识有限也能掌握 URL 和 URI 等概念。

包起来

无论您选择哪种类型的协议来创建 API，请记住每种方法都有其具体情况，需要一定的知识和技能。此外，您将来还需要 API 支持。这就是为什么 REST 尽管有缺陷，但仍然是最流行的 API 开发方法。开发团队的经验对于以 API 为中心的产品的成功至关重要。

也发布在这里。