Обзор дизайна API

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

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

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

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

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

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

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

Вот фрагмент документа OpenAPI, описывающий простой пример приветствия мира 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 в формате 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.

Что произойдет, если я изменю документ?

Каждый документ OpenAPI или GraphQL служит источником достоверной информации на протяжении всего жизненного цикла API. Один и тот же документ используется на каждом этапе жизненного цикла API: от разработки до публикации и мониторинга.

Когда вы редактируете или удаляете документ, это влияет на всю дальнейшую жизнь:

• Если вы редактируете документ, вам необходимо вручную отредактировать связанные артефакты, включая прокси-сервер API и все продукты API, которые предоставляют его ресурсы, а также заново создать справочную документацию API, чтобы отразить изменения, реализованные в документе.
• Если вы удаляете документ, вам необходимо вручную удалить связанные артефакты, включая прокси-сервер API, и отредактировать все продукты API, чтобы удалить связанные ресурсы, а также заново создать справочную документацию API , чтобы отразить удаление документа и его ресурсов.

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

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

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

• Из списка спецификаций, как описано в разделе Создание прокси-сервера API на основе спецификации в списке спецификаций . Примечание . Список спецификаций недоступен в Classic Edge.
• Из диспетчера прокси API, вызвав мастер создания прокси и выбрав создание прокси API из документа OpenAPI, как описано в разделе Использование спецификаций OpenAPI для создания прокси .

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