API 设计概览

您正在查看 Apigee Edge 文档。
转到 Apigee X 文档
信息

在设计阶段,您可以定义 API 的要求。作为 API 设计者,您可以规划您希望向用户呈现的服务,并设计 API 来访问这些服务。您可以创建以下文档之一来捕获您的 API 要求:

  • OpenAPI 文档
  • GraphQL 架构

以下部分详细介绍了 OpenAPI 和 GraphQL 文档及其在 API 生命周期中的作用。 如需了解这两种 API 设计选项的比较,请参阅这篇博文中的 REST 和 GraphQL 比较。

什么是 OpenAPI 规范?


“OpenAPI 计划 (OAI) 专注于根据 Swagger 规范创建、改进和推广供应商中立的 API 描述格式。”如需详细了解 OpenAPI 计划,请访问 https://openapis.org

OpenAPI 文档使用标准格式来描述 RESTful API。OpenAPI 文档采用 JSON 或 YAML 机器可读格式编写,但也便于人类阅读和理解。OpenAPI 规范提供 API 元素的正式描述,例如基本路径、路径和动词、标头、查询参数、内容类型、响应模型等。此外,OpenAPI 文档通常用于生成 API 文档。

以下是摘自描述 Apigee 简单 Hello World 示例的 OpenAPI 文档中的一个代码片段。如需了解详情,请查看 GitHub 上的 OpenAPI 规范。

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

有很多关于 OpenAPI 规范的可靠信息来源。您不妨从 OpenAPI 计划网站入手,您可以在这里找到与 OpenAPI 规范相关的概览、博客和链接。有关架构元素和数据类型的详细说明,请参阅相关规范。

您可以从 OpenAPI 规范代码库下载许多 JSON 和 YAML 格式的示例 OpenAPI 文档。

什么是 GraphQL 架构?

GraphQL 架构描述了 API 中可供客户端查询的数据。

使用 GraphQL 有如下好处:

  • 通过单个端点便可提供对给定操作的所有字段的访问权限
  • 提供了一种强大的查询语言(称为“架构定义语言”),可让您精确访问所需的数据,防止数据过度提取或提取不足
  • 可并行处理查询

如需详细了解 GraphQL,请参阅 graphql.org

下面提供了一个 GraphQL 架构示例,用于定义数据入口点(查询类型)、可用写入操作(更改类型)和数据类型。

type Query {
  Greeting: String
  students: [Student]
}
type Mutation {
  createStudent(firstName: String!, lastName: String!): Student!
}
type Subscription {
  newStudent: Student!
}
type Student {
  Id: ID!
  firstName: String!
  lastName: String!
  password: String!
  collegeId: String!
}

您可以查询 GraphQL 架构,并以 JSON 载荷的形式返回所需的确切数据。

GraphQL 查询和结果

如果修改文档会发生什么情况?

每个 OpenAPI 或 GraphQL 文档都用作整个 API 生命周期内的可靠来源。在 API 生命周期(从开发、发布到监控)的每个阶段都会用到这份文档。

当您修改或删除某个文档时,它会影响以下行:

  • 如果您修改文档,则需要手动修改相关工件(包括 API 代理和公开其资源的任何 API 产品),然后重新生成 API 参考文档,以反映在该文档中实现的更改。
  • 如果您删除文档,则需要手动删除相关工件(包括 API 代理)并修改所有 API 产品以删除相关资源,然后重新生成 API 参考文档,以反映移除的文档及其资源。

根据 OpenAPI 文档创建 API 代理会发生什么情况?

在 Edge 中,您可以根据 OpenAPI 文档创建 API 代理。您只需点击几下,便可自动生成包含路径、参数、条件流和目标端点的 API 代理。然后,您可以添加 OAuth 安全机制、速率限制和缓存等功能。

您可以通过 OpenAPI 文档创建 API 代理,如以下部分所述:

发布 API 时,您需要截取 OpenAPI 文档的快照,以生成 API 参考文档。该快照表示规范存储区中说明文档的特定修订版本。