Обзор проектирования API

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

На этапе проектирования вы определяете требования к API. Как разработчик API, вы планируете сервисы, которые хотите предоставить пользователям, и разрабатываете API для доступа к этим сервисам. Вы создаете один из следующих документов, чтобы зафиксировать требования к API:

  • документ OpenAPI;
  • Схема GraphQL

В разделах ниже приведена дополнительная информация о документах OpenAPI и GraphQL и их роли в жизненном цикле API. Сравнение двух вариантов дизайна API приведено в этой записи блога.

Что такое спецификация OpenAPI?


"OpenAPI Initiative (OAI) занимается созданием, развитием и продвижением независимого от поставщика формата описания API на основе спецификации Swagger". Дополнительную информацию об инициативе OpenAPI можно найти на сайте https://openapis.org.

Документ OpenAPI описывает REST API в стандартном формате. Документ OpenAPI, написанный в формате JSON или YAML, легко читается и понимается как машинами, так и людьми. Спецификация OpenAPI позволяет формально описывать элементы API, такие как базовый путь, пути и глаголы, заголовки, параметры запроса, типы контента, модели ответов и т. д. Кроме того, документ OpenAPI обычно используется для создания документации по API.

Ниже приведен фрагмент документа OpenAPI, описывающий простой пример "Hello, world!" для Apigee. Дополнительную информацию можно найти в спецификации OpenAPI на сайте GitHub.

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 Initiative, где вы найдете обзоры, блоги и ссылки на спецификацию OpenAPI. Подробные описания элементов схемы и типов данных приведены в спецификации.

В репозитории спецификации OpenAPI можно скачать примеры документов OpenAPI в форматах JSON и YAML.

Что такое схема GraphQL?

Схема GraphQL описывает данные, доступные в вашем API для запросов клиента.

Преимущества использования GraphQL:

  • Одна конечная точка предоставляет доступ ко всем полям для определенной операции.
  • Мощный язык запросов, называемый языком определения схемы, позволяет получать именно те данные, которые вам нужны, избегая избыточного или недостаточного объема данных.
  • Запросы обрабатываются параллельно

Подробнее о GraphQL можно узнать на сайте graphql.org.

Ниже приведен пример схемы GraphQL, в которой определены точка входа данных (тип Query), доступные операции записи (тип Mutation) и типы данных.

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, чтобы в ней отразилось удаление документа и его ресурсов.

Что происходит при создании прокси-сервера API на основе документа OpenAPI?

В Edge можно создавать прокси API на основе документов OpenAPI. Всего за несколько кликов вы получите прокси-сервер API с автоматически созданными путями, параметрами, условными потоками и целевыми конечными точками. Затем вы можете добавить такие функции, как безопасность OAuth, ограничение частоты запросов и кеширование.

Вы можете создать прокси-сервер API на основе документа OpenAPI, как описано в следующих разделах:

Когда вы публикуете API, создается снимок документа OpenAPI, на основе которого генерируется справочная документация по API. Этот снимок представляет собой определенную версию документа с описанием в хранилище спецификаций.