Публикуйте свои API

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

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

Обзор публикации API

Процесс публикации API на вашем портале состоит из двух этапов:

  1. Выберите продукт API, который вы хотите опубликовать на своем портале.
  2. Отобразите справочную документацию по API из снимка вашего документа OpenAPI или схемы GraphQL, чтобы разработчики приложений могли узнать о ваших API. (Дополнительную информацию о моментальных снимках см. в разделе Что такое моментальный снимок? ).

Что публикуется на портале?

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

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

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

    Страница API на действующем портале, показывающая две категории и использование изображений.

    • СмартДокс (OpenAPI)

    Когда вы публикуете API с использованием документа OpenAPI, на ваш портал добавляется справочная документация по API SmartDocs.

    Разработчики могут просмотреть справочную документацию по API SmartDocs и использовать панель «Попробуйте этот API» , чтобы сделать запрос API и просмотреть результат. Попробуйте этот API работает с незащищенными конечными точками или с защищенными конечными точками с использованием базовой аутентификации, ключа API или аутентификации OAuth в зависимости от метода безопасности, определенного в вашем документе OpenAPI. Для OAuth поддерживаются следующие потоки: код авторизации, пароль и учетные данные клиента.

    Страница справочной документации API с выносками, показывающими, как авторизовать вызов API, открепить панель «Попробуйте этот API», загрузить соответствующую спецификацию и выполнить API.

    Нажмите чтобы развернуть панель «Попробуйте этот API». Расширенная панель позволяет просматривать вызов Curl и примеры кода в различных форматах, таких как HTTP, Python, Node.js и других, как показано ниже.

    Расширенная панель «Попробуйте этот API»

    GraphQL Explorer

    Когда вы публикуете API с использованием схемы GraphQL, на ваш портал добавляется GraphQL Explorer. GraphQL Explorer — это интерактивная площадка для выполнения запросов к вашему API. Проводник основан на GraphiQL , эталонной реализации GraphQL IDE, разработанной GraphQL Foundation.

    Разработчики могут использовать GraphQL Explorer для изучения интерактивной документации на основе схемы, построения и выполнения запросов, просмотра результатов запросов и загрузки схемы. Чтобы защитить доступ к вашему API, разработчики могут передавать заголовки авторизации на панели «Заголовки запросов» .

    Дополнительную информацию о GraphQL см. на сайтеgraphql.org .

    GraphQL Explorer на портале

    Что такое снимок?

    Каждый документ OpenAPI или GraphQL служит источником достоверной информации на протяжении всего жизненного цикла API. Один и тот же документ используется на каждом этапе жизненного цикла API: от разработки до публикации и мониторинга. Изменяя документ, вы должны осознавать влияние этих изменений на ваш API на других этапах жизненного цикла, как описано в разделе «Что произойдет, если я изменю документ?»

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

    Об URL-адресах обратного вызова

    Если вашим приложениям требуется URL-адрес обратного вызова, например при использовании типа предоставления кода авторизации OAuth 2.0 (часто называемого «трехсторонним OAuth»), вы можете потребовать от разработчиков указать URL-адрес обратного вызова при регистрации своих приложений. URL-адрес обратного вызова обычно указывает URL-адрес приложения, предназначенного для получения кода авторизации от имени клиентского приложения. Дополнительные сведения см. в разделе Реализация типа предоставления кода авторизации .

    Вы можете настроить, требуется или нет URL-адрес обратного вызова во время регистрации приложения при добавлении API на ваш портал . Вы можете изменить этот параметр в любое время, как описано в разделе «Управление URL-адресом обратного вызова для API» .

    При регистрации приложения разработчики должны ввести URL-адрес обратного вызова для всех API, которым он требуется, как описано в разделе «Регистрация приложений» .

    Настройте свой прокси-сервер API для поддержки «Попробуйте этот API»

    Прежде чем публиковать свои API с использованием документа OpenAPI, вам необходимо настроить прокси-сервер API для поддержки выполнения запросов на панели «Попробуйте этот API» в справочной документации по API SmartDocs, как показано ниже:

    • Добавьте поддержку CORS в свои прокси API, чтобы обеспечить выполнение запросов между источниками на стороне клиента.

      CORS — это стандартный механизм, который позволяет вызовам JavaScript XMLHttpRequest (XHR), выполняемым на веб-странице, взаимодействовать с ресурсами из доменов, не являющихся источниками происхождения. CORS — это широко распространенное решение « политики одного и того же происхождения », которая применяется всеми браузерами.

    • Обновите конфигурацию прокси-сервера API, если вы используете базовую аутентификацию или OAuth2.

    В следующей таблице приведены требования к конфигурации прокси-сервера API для поддержки панели «Попробуйте этот API» в справочной документации API SmartDocs на основе доступа с аутентификацией.

    Авторизация доступа Требования к конфигурации политики
    Нет или ключ API Добавьте поддержку CORS в свой прокси API. Для удобства воспользуйтесь примером решения CORS , представленным на GitHub, или выполните действия, описанные в разделе Добавление поддержки CORS в прокси-сервер API .
    Базовая аутентификация Выполните следующие шаги:
    1. Добавьте поддержку CORS в свой прокси API. Для удобства воспользуйтесь примером решения CORS , представленным на GitHub, или выполните действия, описанные в разделе Добавление поддержки CORS в прокси-сервер API .
    2. В политике «Добавить CORS AssignMessage» убедитесь, что заголовок Access-Control-Allow-Headers включает атрибут authorization . Например: 
      <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
    ОАут2
    1. Добавьте поддержку CORS в свой прокси API. Для удобства воспользуйтесь примером решения CORS , представленным на GitHub, или выполните действия, описанные в разделе Добавление поддержки CORS в прокси-сервер API .
    2. В политике «Добавить CORS AssignMessage» убедитесь, что заголовок Access-Control-Allow-Headers включает атрибут authorization . Например: 
      <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
    3. Исправьте несовместимое с RFC поведение в вашей политике OAuth2. Для удобства воспользуйтесь примером решения OAuth2 , представленным на GitHub, или выполните следующие действия:
      • Убедитесь, что для элемента <GrantType> в политике OAuth2 установлено значение request.formparam.grant_type (параметр формы). Дополнительные сведения см. в разделе <GrantType> .
      • Убедитесь, что для token_type в политике OAuth2 установлено значение Bearer , а не BearerToken по умолчанию.

    Изучите каталог API

    Чтобы просмотреть каталог API: 1. Выберите «Опубликовать» > «Порталы» и выберите свой портал. 2. Нажмите Каталог API на главной странице портала. Альтернативно вы можете выбрать каталог API в раскрывающемся меню портала на верхней панели навигации.

    На вкладке API в каталоге API отображается список API, добавленных на ваш портал.

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

    Как показано на предыдущем рисунке, вкладка API позволяет:

    Добавьте API на свой портал

    Чтобы добавить API на ваш портал:

    1. Доступ к каталогу API .
    2. Откройте вкладку API , если она еще не выбрана.

    3. Нажмите + .

      Откроется диалоговое окно «Добавление продукта API в каталог».

    4. Выберите продукт API, который вы хотите добавить на свой портал.

    5. Нажмите Далее . Откроется страница сведений об API.

    6. Настройте содержимое справочной документации API и ее видимость на портале:

      Поле Описание
      Опубликовано Выберите Опубликовано , чтобы опубликовать API на вашем портале. Снимите флажок, если вы не готовы опубликовать API. Вы можете изменить этот параметр позже, как описано в разделе Публикация или отмена публикации API на вашем портале .
      Отображать заголовок Обновите название вашего API, отображаемое в каталоге. По умолчанию используется имя продукта API. Вы можете изменить отображаемый заголовок позже, как описано в разделе «Редактирование отображаемого заголовка и описания» .
      Описание дисплея Обновите описание вашего API, отображаемое в каталоге. По умолчанию используется описание продукта API. Вы можете изменить описание отображения позже, как описано в разделе «Редактирование заголовка и описания отображения» .
      Требовать от разработчиков указания URL-адреса обратного вызова Включите этот параметр, если вы хотите, чтобы разработчики приложений указывали URL-адрес обратного вызова . Вы можете добавить или обновить URL-адрес обратного вызова позже, как описано в разделе «Управление URL-адресом обратного вызова для API» .
      Документация по API Чтобы использовать документ OpenAPI:
      1. Выберите документ OpenAPI .
      2. Нажмите Выбрать документ .
      3. Выполните один из следующих шагов:
        • Перейдите на вкладку «Мои спецификации» и выберите спецификацию в хранилище спецификаций.
        • Перейдите на вкладку «Загрузить файл» и загрузите файл.
        • Перейдите на вкладку «Импорт из URL-адреса» и импортируйте спецификацию из URL-адреса.
      4. Нажмите «Выбрать» .

      Чтобы использовать схему GraphQL:

      1. Выберите схему GraphQL .
      2. Нажмите «Выбрать документ» .
      3. Перейдите и выберите схему GraphQL.
      4. Нажмите «Выбрать» .

      Альтернативно вы можете выбрать «Нет документации» и добавить ее позже, после добавления API, как описано в разделе «Управление снимком документа» .

      видимость API

      Если вы не зарегистрировались в бета-версии функции управления аудиторией , выберите один из следующих вариантов:

      • Анонимные пользователи , чтобы все пользователи могли просматривать API.
      • Зарегистрированные пользователи , чтобы разрешить просмотр API только зарегистрированным пользователям.

      Если вы зарегистрировались на бета-версию функции управления аудиторией , выберите один из следующих вариантов:

      • Публичный (видимый всем), чтобы все пользователи могли просматривать API.
      • Аутентифицированные пользователи , чтобы разрешить просмотр API только зарегистрированным пользователям.
      • Выбранные аудитории, чтобы выбрать конкретные аудитории, которым вы хотите иметь возможность просматривать API.

      Управлять видимостью аудитории можно позже, как описано в разделе Управление видимостью API на портале .

      Показать изображение Чтобы отобразить изображение на карточке API на странице API, нажмите «Выбрать изображение» . В диалоговом окне «Выбор изображения» выберите существующее изображение, загрузите новое изображение или укажите URL-адрес внешнего изображения и нажмите «Выбрать» . Просмотрите миниатюру API и нажмите «Выбрать» . Вы можете добавить изображение позже, как описано в разделе «Управление изображением для карты API» . При указании изображения с внешним URL-адресом изображение не будет загружено в ваши ресурсы; кроме того, загрузка изображения на интегрированном портале будет зависеть от его доступности, которая может быть заблокирована или ограничена политиками безопасности контента .
      Категории

      Добавьте категории, к которым будет помечен API, чтобы разработчики приложений могли находить связанные API на странице API. Чтобы определить категорию:

      • Выберите категорию из раскрывающегося списка.
      • Добавьте новую категорию, введя ее имя и нажав Enter . Новая категория будет добавлена ​​на страницу «Категории» и станет доступной при добавлении или редактировании других API.

    7. Нажмите Сохранить .

    Управление снимком документа

    После публикации API вы в любой момент можете сделать новый снимок документа OpenAPI или GraphQL, чтобы обновить справочную документацию по API, опубликованную на вашем портале.

    Чтобы управлять снимком документа:

    1. Доступ к каталогу API .
    2. Откройте вкладку API , если она еще не выбрана.
    3. Нажмите на строку API, который вы хотите изменить.
    4. Проверьте статус моментального снимка. Если дата устарела, отображается следующее сообщение: Значок и сообщение о том, что снимок устарел
    5. Нажмите значок редактирования .
    6. Выполните одну из следующих задач:
      • Чтобы обновить снимок устаревшего документа OpenAPI, нажмите «Обновить снимок» .
      • Чтобы изменить документ, который используется для создания документации для API, в разделе «Документация API» нажмите «Выбрать документ» и выберите новый документ.
    7. Нажмите Сохранить .

    Справочная документация API отображается из документа и добавляется на страницу справки по API. Статус снимка обновляется до текущего:

    Значок и сообщение указывают на то, что снимок является текущим.

    Опубликовать или отменить публикацию API на вашем портале

    Чтобы опубликовать или отменить публикацию API на вашем портале:

    1. Доступ к каталогу API .
    2. Откройте вкладку API , если она еще не выбрана.
    3. Щелкните строку API, который вы хотите изменить.
    4. Нажмите Значок редактирования .
    5. В разделе «Сведения об API» выберите или снимите флажок «Опубликовано» (указан в каталоге), чтобы опубликовать или отменить публикацию API на вашем портале соответственно.
    6. Нажмите Сохранить .

    Управляйте видимостью API на вашем портале

    Управляйте видимостью API на своем портале, разрешив доступ к:

    Чтобы управлять видимостью API на вашем портале:

    1. Доступ к каталогу API .
    2. Откройте вкладку API , если она еще не выбрана.
    3. Щелкните строку API, который вы хотите изменить.
    4. Нажмите Значок редактирования .
    5. В разделе «Видимость API» выберите один из следующих вариантов:

    6. Выберите настройку видимости. Если вы зарегистрировались для участия в бета-версии функции «Аудитории» , выберите один из следующих вариантов:

      • Открытый (видимый всем), чтобы все пользователи могли просматривать страницу.
      • Аутентифицированные пользователи , чтобы разрешить просмотр страницы только зарегистрированным пользователям.
      • Выбранные аудитории , чтобы выбрать конкретные аудитории, которым вы хотите иметь возможность просматривать страницу. См. раздел Управление аудиторией вашего портала .
      В противном случае выберите один из следующих вариантов:
      • Анонимные пользователи , чтобы разрешить всем пользователям просматривать страницу.
      • Зарегистрированные пользователи , чтобы разрешить просмотр страницы только зарегистрированным пользователям.

    7. Нажмите «Отправить» .

    Управление URL-адресом обратного вызова для API

    Управляйте URL-адресом обратного вызова для API. См. раздел «Об URL-адресах обратного вызова» .

    Чтобы управлять URL-адресом обратного вызова для API:

    1. Доступ к каталогу API .
    2. Откройте вкладку API , если она еще не выбрана.
    3. Нажмите на строку API, который вы хотите изменить.
    4. Нажмите Значок редактирования .
    5. В разделе «Сведения об API» выберите или снимите флажок «Опубликовано» (указан в каталоге), чтобы опубликовать или отменить публикацию API на вашем портале соответственно.
    6. Нажмите Сохранить .

    Управление изображением карты API

    Управляйте изображением, которое отображается вместе с карточкой API на странице API, добавляя или изменяя текущее изображение.

    Чтобы управлять изображением карты API:

    1. Доступ к каталогу API .
    2. Откройте вкладку API , если она еще не выбрана.
    3. Нажмите на строку API, который вы хотите изменить.
    4. Нажмите Значок редактирования .

    5. В деталях API:

      • Нажмите «Выбрать изображение» , чтобы указать или загрузить изображение, если в данный момент изображение не выбрано.
      • Нажмите «Изменить изображение» , чтобы указать или загрузить другое изображение.
      • Нажмите x на изображении, чтобы удалить его.

      При указании изображения укажите либо изображение с внешним URL-адресом, используемым для элемента каталога, либо путь к файлам изображений, хранящимся на портале , например, /files/book-tree.jpg . При указании URL-адреса внешнего изображения изображение не будет загружено в ваши ресурсы; кроме того, загрузка изображения на интегрированном портале будет зависеть от его доступности, которая может быть заблокирована или ограничена политиками безопасности контента .

    6. Нажмите Сохранить .

    Пометьте API, используя категории

    Пометьте API, используя категории, одним из следующих способов:

    • Управляйте категориями, к которым помечен API, при редактировании API, как описано ниже.
    • Управляйте API, помеченными в категории, при редактировании категории .

    Чтобы пометить API по категориям при редактировании API:

    1. Доступ к каталогу API .
    2. Откройте вкладку API , если она еще не выбрана.
    3. Нажмите на строку API, который вы хотите изменить.
    4. Нажмите Значок редактирования .
    5. Нажмите в поле «Категории» и выполните одно из следующих действий:
      • Выберите категорию из раскрывающегося списка.
      • Добавьте новую категорию, введя ее имя и нажав Enter . Новая категория будет добавлена ​​на страницу «Категории» и станет доступной при добавлении или редактировании других API.
    6. Повторите действия, чтобы пометить API для других категорий.
    7. Нажмите Сохранить .

    Отредактируйте отображаемый заголовок и описание.

    Чтобы отредактировать отображаемый заголовок и описание:

    1. Доступ к каталогу API .
    2. Откройте вкладку API , если она еще не выбрана.
    3. Нажмите на строку API, который вы хотите изменить.
    4. Нажмите Значок редактирования .
    5. При необходимости отредактируйте поля «Заголовок дисплея» и «Описание отображения» .
    6. Нажмите Сохранить .

    Удалите API с вашего портала

    Чтобы удалить API с вашего портала:

    1. Доступ к каталогу API .
    2. Выберите API , если они еще не выбраны.
    3. Наведите курсор на API в списке, чтобы отобразить меню действий.
    4. Нажмите Значок редактирования .

    Управляйте категориями, используемыми для обнаружения связанных API.

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

    Изучите страницу категорий

    Чтобы просмотреть страницу категорий:

    1. Выберите «Опубликовать» > «Порталы» и выберите свой портал.
    2. Нажмите Каталог API на главной странице портала.

      Альтернативно вы можете выбрать каталог API в раскрывающемся меню портала на верхней панели навигации.

    3. Откройте вкладку «Категории» .

    На вкладке «Категории» в каталоге API отображается список категорий, определенных для вашего портала.

    Вкладка «Категории», на которой показано название категории, а также имена и общее количество назначенных API.

    Как показано на предыдущем рисунке, страница API позволяет вам:

    Добавить категорию

    Добавьте категорию одним из следующих способов:

    Новая категория будет добавлена ​​на страницу «Категории» и станет доступной при добавлении или редактировании других API.

    Чтобы вручную добавить категорию:

    1. Откройте страницу категорий .
    2. Нажмите + .
    3. Введите название новой категории.
    4. При необходимости выберите один или несколько API для добавления в категорию.
    5. Нажмите Создать .

    Изменить категорию

    Чтобы отредактировать категорию:

    1. Откройте страницу категорий .
    2. Нажмите .
    3. Отредактируйте название категории.
    4. Добавьте или удалите теги API.
    5. Нажмите Сохранить .

    Удалить категорию

    Когда вы удаляете категорию, все теги API этой категории также удаляются.

    Чтобы удалить категорию:

    1. Откройте страницу категорий .
    2. Наведите курсор на категорию, которую вы хотите отредактировать, чтобы отобразить меню действий.
    3. Нажмите .
    4. Отредактируйте название категории.
    5. Добавьте или удалите API.
    6. Нажмите Сохранить .

    Устранение неполадок с опубликованными API

    В следующих разделах представлена ​​информация, которая поможет вам устранить конкретные ошибки с нашими опубликованными API.

    Ошибка: не удалось получить ошибку, возвращаемую при использовании Попробуйте этот API

    Если при использовании «Попробуйте этот API» возвращается ошибка TypeError: Failed to fetch , рассмотрите следующие возможные причины и решения:

    • В случае ошибок со смешанным контентом ошибка может быть вызвана известной проблемой swagger-ui . Один из возможных обходных путей — убедиться, что вы указываете HTTPS перед HTTP в определении schemes в вашем документе OpenAPI. Например:

      schemes:
   - https
   - http

    • При возникновении ошибок ограничения совместного использования ресурсов между источниками (CORS) убедитесь, что CORS поддерживается для ваших прокси-серверов API. CORS — это стандартный механизм, который позволяет выполнять запросы между источниками на стороне клиента. См. раздел Настройка прокси-сервера API для поддержки «Попробуйте этот API» .

    Ошибка: заголовок «Access-Control-Allow-Origin» содержит несколько значений «*, *», но разрешено только одно.

    При использовании «Попробуйте этот API» вы можете получить следующее сообщение об ошибке, если заголовок Access-Control-Allow-Origin уже существует:

    The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.

    Чтобы исправить эту ошибку, измените политику AssignMessage, чтобы использовать <Set> для установки заголовков CORS вместо <Add> , как показано во фрагменте ниже. Дополнительную информацию можно найти в соответствующей статье сообщества .

    <AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors">
    <DisplayName>Add CORS</DisplayName>
    <FaultRules/>
    <Properties/>
    <Set>
        <Headers>
            <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header>
            <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header>
            <Header name="Access-Control-Max-Age">3628800</Header>
            <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

    Ошибка: поле заголовка запроса не разрешено.

    Если при использовании «Попробуйте этот API» вы получаете сообщение об ошибке Request header field not allowed , как показано в примере ниже, вам может потребоваться обновить заголовки, поддерживаемые в политике CORS. Например:

    Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response

    В этом примере вам необходимо добавить заголовок content-type в раздел Access-Control-Allow-Headers в вашей политике CORS AssignMessage, как описано в разделе «Прикрепление политики добавления CORS к новому прокси-серверу API» .

    Ошибка: доступ запрещен при вызове прокси-сервера API с использованием OAuth2.

    Политика Apigee OAuthV2 возвращает ответ токена, который содержит определенные свойства, не соответствующие RFC. Например, политика вернет токен со значением BearerToken вместо ожидаемого значения Bearer , соответствующего требованиям RFC. Этот неверный ответ token_type может привести к ошибке Access denied при использовании «Попробуйте этот API».

    Чтобы устранить эту проблему, вы можете создать политику JavaScript или AssignMessage для преобразования выходных данных политики в совместимый формат. Дополнительные сведения см. в разделе Поведение, не соответствующее RFC .