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

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

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

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

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

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

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

Документ OpenAPI использует стандартный формат для описания RESTful API. Написанный в формате JSON или YAML, документ OpenAPI является машиночитаемым, но при этом легко читается и понимается человеком. Спецификация 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 относятся:

• Единая точка доступа обеспечивает доступ ко всем полям для данной операции.
• Мощный язык запросов, называемый языком определения схемы (Schema Definition Language), позволяет получать доступ именно к тем данным, которые вам необходимы, предотвращая избыточную или недостаточную выборку данных.
• Обработка запросов происходит параллельно.

Для получения дополнительной информации о 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-прокси на основе спецификации из списка спецификаций» . Примечание : список спецификаций недоступен в классической версии Edge.
• Из менеджера API-прокси, вызвав мастер создания прокси и выбрав создание API-прокси на основе документа OpenAPI, как описано в разделе «Использование спецификаций OpenAPI для генерации прокси» .

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