Что такое управление API?

В контексте архитектуры или проектирования системы управление API обычно относится к настраиваемому, высокофункциональному обратному прокси-серверу, который используется для управления доступом клиентов (внешних, внутренних или иных) к API, конечной точке или методу. Обычно используемое с RESTful API, но не исключительно, управление API обеспечивает уровень управления запросами и защиты, чтобы входящий запрос можно было проверить, изменить и обработать, а ответ, возвращающийся от серверной системы, можно было дополнительно изменить или обработать. Некоторые организации могут использовать корпоративную сервисную шину для достижения аналогичных целей. Корпоративная сервисная шина — это гибко определяемый термин для класса технологий, которые включают дополнительные аспекты, связанные с этим компонентом, но могут извлечь выгоду из того же набора рекомендаций для сервисов управления API.

Примеры систем управления API включают эти и другие:

• Управление API Azure
• Шлюз API AWS
• Mulesoft Anypoint
• Apigee
• Kong
• Boomi

Общие сведения об управлении API

Поведение управления API отличается от традиционного обратного прокси-сервера, который обычно перенаправляет весь шаблон HTTP-трафика на внутренний сервер. Например:

<external-host>:443/server/rest/services/* » <internal-host>>:6443/arcgis/rest/services/*

Управление API часто включает в себя выборку отдельных путей URI API и методов HTTP (т.е. POST в /routes/extract и PATCH в /routes/<routeid>), что означает, что каждый отдельный метод или шаблон должен быть определен, а также что каждый шаблон может иметь различные правила, поведение и серверные приемники или сервисы. Это часто используется при создании новых API или систем, где существующий набор веб-сервисов не существует, или при реализации архитектуры в стиле микросервисов, где различные серверные компоненты или системы отвечают за обслуживание отдельных запросов API. В некоторых случаях управление API может использовать определение API серверной части, например спецификацию OpenAPI, для создания множества конечных точек или методов интерфейса.

Управление API также обычно включает в себя множество других опций обработки, которые либо манипулируют содержимым запроса (настройка или переписывание пути, добавление или изменение заголовка, изменение назначения на основе содержимого тела POST), применяют некоторую фильтрацию к запросу (ограничение скорости, блокировка определенных диапазонов IP-адресов, требование ключей API) или работают с ответом (скрывают имена серверов, удаляют заголовки ответа, добавляют отпечаток пальца или идентификатор). Эти операции определяются на уровне управления API и работают с каждым запросом по мере его отправки и создания ответа.

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

Управление API и ArcGIS

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

• Управление API обычно лучше всего работает в качестве архитектурного шаблона с автономными развертываниями ArcGIS Server. Обработка обмена токенами и проверки, необходимых для интегрированного сервера в рамках развертывания ArcGIS Enterprise, значительно сложнее и потребует либо расширенной конфигурации ArcGIS, либо конфигурации управления API и знаний для обработки различных запросов аутентификации и конечных точек.
• Системы управления API обычно анонимно обращаются к сервисам ArcGIS REST, а запросы от «сервиса» управления API отправляются в серверную часть ArcGIS без дальнейших шагов аутентификации. В то время как ArcGIS поддерживает множество шаблонов аутентификации, от встроенных имен пользователей и паролей до SAML и OIDC, шаблон управления API часто предполагает, что внутренний API анонимно доступен для запросов, исходящих из сервиса управления API.
• Управление API обычно следует использовать для предоставления доступа к конкретным сервисам или конечным точкам, а не ко всем сайтам ArcGIS Server. Если ваша цель состоит в том, чтобы предоставить доступ ко всему сайту, традиционный обратный прокси обычно является лучшим решением, которое будет более совместимо с рабочими процессами.
• ArcGIS обычно предоставляет более подробные REST API, что означает, что сервис управления API должен поддерживать либо гибкие шаблоны подстановочных знаков, либо только прямые определенные пути. Это особенно актуально, если цель состоит в том, чтобы предоставить сервис клиентскому программному обеспечению ArcGIS, которое спроектировано таким образом, чтобы ожидать полностью доступного API (где можно получить доступ ко всем методам и ресурсам).

Например:

• Достаточно переадресовать этот запрос, чтобы получить подробную информацию о конкретном сервисе:
  • /arcgis/rest/services/ServiceName/MapServer
• Однако, если вы хотите поддерживать функциональность картографического сервиса и векторного слоя, вы должны дополнительно перенаправить следующие типы запросов:
  • /arcgis/rest/services/ServiceName/MapServer/exportImage
  • /arcgis/rest/services/ServiceName/MapServer/0/query
  • /arcgis/rest/services/ServiceName/MapServer/1/query

Рекомендации

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

• Если цель состоит в том, чтобы применять аутентификацию только на уровне сервиса управления API и чтобы все действия пользователей использовали эту конечную точку, сервисы ArcGIS, определенные как серверные части, обычно должны быть настроены как незащищенные или «доступные для всех» с публичным или организационным доступом, ограниченным через сетевую конструкцию или брандмауэр, с доступом только через сервис управления API.
• Рассмотрите URL-адреса веб-контекста и реализацию заголовков, связанных с прокси, чтобы гарантировать, что компонент ArcGIS Server, стоящий за управлением API, знает о проксировании и возвращает действительные URL-адреса, где это возможно.
• Ссылки, возвращаемые из запроса через сервис управления API, должны быть проверены и изменены, чтобы использовать правильное имя хоста и контекст для дальнейших запросов. Например, асинхронный запрос сервиса печати возвращает окончательный URL-адрес результирующего PDF-файла, который затем будет запрошен пользователем, этот URL-адрес может ссылаться на внутреннее имя хоста, а содержимое может быть переписано в системе управления API.

Работа с API-ключами и аутентификация

Управление API по определению не включает уровень аутентификации, но многие организации хотят применять аутентификацию к своим конечным точкам управления API в целях проверки пользователей и управления авторизацией. Распространенные методы проверки подлинности на основе управления API включают использование API или ключа подписки, а также интеграцию с методами проверки подлинности на основе OAuth с существующим поставщиком удостоверений (IdP). Каждый из этих шаблонов может создать некоторые проблемы с рабочими процессами интеграции ArcGIS.

Имейте в виду, что методы аутентификации клиентов на основе управления API могут быть несовместимы со стандартными клиентами ArcGIS. Например, если система управления API требует аутентификации на основе заголовков с использованием заголовка, специфичного для сервиса, или заголовка Bearer Authorization, стандартные клиенты ArcGIS не смогут динамически добавлять этот заголовок в запросы для поддержки доступа к этому сервису. Аналогичным образом, ключи API могут быть общим уровнем аутентификации, добавляемым через интерфейс управления API, но разработчики приложений должны знать об этом требовании и иметь возможность добавлять его в запросы, чтобы интегрировать эти сервисы в приложение. Различные SDK ArcGIS и шаблоны регистрации сервисов могут поддерживать этот тип ключа подписки или шаблона аутентификации ключа API, но их следует тщательно протестировать, прежде чем предполагать, что шаблон аутентификации подходит.

Аутентификация на основе OAuth для управления API сопряжена и с другими проблемами. При разработке пользовательского приложения с использованием поддерживаемого пакета SDK может быть относительно просто предоставить первоначальное перенаправление в сервис OAuth, вернуть токен или код и использовать этот токен для добавления к дальнейшим запросам в этом сеансе. Однако при использовании готового приложения ArcGIS эту конфигурацию гораздо сложнее успешно использовать, поскольку эти клиенты ожидают прямого доступа к геосервисам ArcGIS без дополнительных шагов аутентификации, которые не управляются ArcGIS.

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

• Ключи API или подписки должны поддерживать использование в качестве параметров запроса URL. Аутентификация на основе заголовка может поддерживаться для некоторых рабочих процессов, таких как пользовательское приложение на основе Esri Maps SDK или интеграция на основе Python, но для большинства существующих интерфейсов использование заголовка аутентификации, отличного от ArcGIS, в настоящее время невозможно.
• Ключи API могут быть добавлены к элементу ресурсов, созданному в последних версиях ArcGIS Online или ArcGIS Enterprise, либо в качестве пользовательского параметра, предоставленного при создании элемента, либо непосредственно к URL, зарегистрированному с элементом. Тщательно протестируйте эти параметры, чтобы оценить, обеспечивают ли они достаточный доступ к запрашиваемому содержимому.
• При использовании сервисов, защищенных ключами API в ArcGIS Pro, рабочий процесс Добавить данные из пути также поддерживает использование пользовательских параметров.