掌握API架构

第 1 章 设计、构建和指定 API

本作品已使用人工智能进行翻译。欢迎您提供反馈和意见：[e-mail]

在设计和构建应用程序接口时，你会遇到很多选择。 使用现代技术和框架构建服务的速度快得令人难以置信，但创建一种持久的方法则需要深思熟虑。 在本章中，我们将探索 REST 和 RPC，以便为案例研究中的生产者和消费者关系建模。

您将了解标准如何帮助缩短设计决策时间并避免潜在的兼容性问题。 您将了解 OpenAPI 规范、团队的实际用途以及版本管理的重要性。

基于 RPC 的交互是使用模式指定的；为了与 REST 方法进行比较和对比，我们将探讨 gRPC。 考虑到 REST 和 gRPC，我们将研究在如何为交换建模时需要考虑的不同因素。 我们将研究在同一服务中同时提供 REST 和 RPC API 的可能性，以及这样做是否正确。

案例研究：设计与会者 API

在 的导言中，我们决定迁移传统的会议系统，转向更加 API 驱动的架构。 作为实现这一转变的第一步，我们将创建一个新的出席者服务，该服务将公开一个匹配的出席者 API。 我们还提供了一个狭义的 API 定义。 为了有效地进行设计，我们需要更广泛地考虑生产者和消费者之间的交换，更重要的是生产者和消费者是谁。 生产者由出席者团队拥有。该团队维护着两个关键关系：

• 参会者团队拥有生产者，传统会议团队拥有消费者。这两个团队之间关系密切，结构上的任何变化都很容易协调。 生产者/消费者服务之间的强大凝聚力是有可能实现的。

• 参会者团队拥有生产者，外部 CFP 系统团队拥有消费者。 这两个团队之间存在关系，但任何更改都需要协调，以免破坏集成。 需要松散的耦合，需要谨慎管理破坏性更改。

我们将在本 章中对设计和构建与会者 API 的方法进行比较和对比。

REST 简介

呈现状态传输（REST）是一套架构约束，最常应用的是以 HTTP 作为底层传输协议。Roy Fielding 的论文《架构风格和基于网络的软件架构设计》提供了 REST 的完整定义。从实用的角度来看，要被视为 RESTful，您的应用程序接口必须确保：

• 在生产者与消费者的互动模型中，生产者对消费者可以互动的资源进行建模。

• 从生产者到消费者的请求是无状态的，这意味着生产者不会缓存之前请求的详细信息。为了在给定资源上建立一个请求链，消费者必须向生产者发送所需的信息以供处理。

• 请求是可缓存的，这意味着生产者可以在适当的时候向消费者提供提示。在 HTTP 中，这通常是通过头中包含的信息提供的。

• 向消费者传达的是一个统一的界面。稍后您将探讨动词、资源和其他模式的使用。

• 它是一个分层系统，抽象掉了 REST 接口背后系统的复杂性。例如，消费者不应该知道或关心他们是否在与数据库或其他服务交互。

REST 和 HTTP 示例介绍

让我们看看 一个通过 HTTP 进行 REST 的例子。 下面的交换是一个GET请求，其中 GET 代表方法或动词。 像 GET 这样的动词描述了对特定资源采取的行动；在这个例子中，我们考虑的是attendees资源。 我们传递了一个Accept标头，以定义消费者想要检索的内容类型。 REST 在正文中定义了表示法的概念，并允许在标头中定义表示法元数据。

在本章的示例中，我们在--- 分隔符上方表示请求，在下方表示响应：

GET http://mastering-api.com/attendees Accept: application/json ...