Лучшие практики проектирования и разработки API-прокси

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

Цель данного документа — предоставить набор стандартов и лучших практик для разработки с использованием Apigee Edge. В нем рассматриваются такие темы, как проектирование, кодирование, использование политик, мониторинг и отладка. Информация собрана на основе опыта разработчиков, работающих с Apigee и успешно внедряющих API-приложения. Этот документ постоянно обновляется.

В дополнение к приведенным здесь рекомендациям, вам также может пригодиться сообщение в сообществе Apigee Edge Antipatterns .

стандарты развития

Комментарии и документация

  • Добавьте встроенные комментарии в конфигурации ProxyEndpoint и TargetEndpoint. Комментарии улучшают читаемость потока, особенно в тех случаях, когда имена файлов политик недостаточно информативны для описания базовой функциональности потока.
  • Оставляйте полезные комментарии. Избегайте банальных замечаний.
  • Используйте одинаковые отступы, интервалы, вертикальное выравнивание и т. д.

Кодирование в стиле фреймворка

В стиле фреймворкового программирования ресурсы API-прокси хранятся в собственной системе контроля версий для повторного использования в локальных средах разработки. Например, чтобы повторно использовать политику, сохраните её в системе контроля версий, чтобы разработчики могли синхронизировать её и использовать в своих собственных средах разработки прокси.

  • Чтобы обеспечить принцип DRY («не повторяйся»), по возможности, конфигурации политик и скрипты должны реализовывать специализированные, многократно используемые функции. Например, отдельная политика для извлечения параметров запроса из сообщений запроса может называться ExtractVariables.ExtractRequestParameters . Отдельная политика для внедрения заголовков CORS может называться AssignMessage.SetCORSHeaders . Затем эти политики можно хранить в вашей системе контроля версий и добавлять к каждому API-прокси, которому необходимо извлекать параметры или устанавливать заголовки CORS, без необходимости создания избыточных (и, следовательно, менее управляемых) конфигураций.
  • Удалите неиспользуемые политики и ресурсы (JavaScript, Java, XSLT и т. д.) из API-прокси, особенно крупные ресурсы, которые могут замедлить процедуры импорта и развертывания.

Правила именования

  • Атрибут « name политики» и имя XML-файла политики должны совпадать.
  • Атрибуты name политики Script и ServiceCallout, а также имя файла ресурсов должны совпадать.
  • DisplayName должен точно описывать функцию политики для человека, который никогда раньше не работал с этим API-прокси.
  • Называйте политики в соответствии с их функцией. Apigee рекомендует установить единообразную систему именования для ваших политик. Например, используйте короткие префиксы, за которыми следует последовательность описательных слов, разделенных дефисами. Например, AM-xxx для политик AssignMessage. См. также инструмент apigeelint .
  • Используйте соответствующие расширения для файлов ресурсов: .js для JavaScript, .py для Python и .jar для JAR-файлов Java.
  • Названия переменных должны быть единообразными. Если вы выбираете стиль, например camelCase или under_score, используйте его во всем API-прокси.
  • По возможности используйте префиксы переменных для организации переменных в зависимости от их назначения, например, Consumer.username и Consumer.password .

разработка API-прокси

Первоначальные соображения по проектированию

  • Для получения рекомендаций по проектированию RESTful API скачайте электронную книгу «Web API Design: The Missing Link» .
  • Используйте политики и функциональные возможности Apigee Edge везде, где это возможно, для создания API-прокси. Избегайте написания всей логики прокси на JavaScript, Java или Python.
  • Создавайте потоки событий организованным образом. Предпочтительнее использовать несколько потоков, каждый с одним условием, чем несколько условных привязок к одному и тому же предварительному и последующему потокам.
  • В качестве «подстраховки» создайте прокси-сервер API по умолчанию с базовым путем ProxyEndpoint / . Это можно использовать для перенаправления базовых запросов API на сайт разработчика, для возврата пользовательского ответа или для выполнения другого действия, более полезного, чем возврат messaging.adaptors.http.flow.ApplicationNotFound по умолчанию.
  • Используйте ресурсы TargetServer для отделения конфигураций TargetEndpoint от конкретных URL-адресов, что позволит поддерживать продвижение между средами.
    См. раздел «Балансировка нагрузки между серверами бэкэнда» .
  • Если у вас несколько правил маршрутизации (RouteRules), создайте одно из них в качестве «правила по умолчанию», то есть как правило маршрутизации без условий. Убедитесь, что правило маршрутизации по умолчанию определено последним в списке условных маршрутов. Правила маршрутизации оцениваются сверху вниз в ProxyEndpoint.
    См. справочник по настройке API-прокси .
  • Размер пакета API-прокси: размер пакета API-прокси не может превышать 15 МБ. В Apigee Edge for Private Cloud вы можете изменить ограничение размера, изменив свойство thrift_framed_transport_size_in_mb в следующих местах: cassandra.yaml (в Cassandra) и conf/apigee/management-server/repository.properties.
  • Версионирование API: С мнением и рекомендациями Apigee по версионированию API можно ознакомиться в разделе «Версионирование» в электронной книге «Проектирование веб-API: недостающее звено ».

Включение CORS

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

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

Для получения информации о включении CORS в ваших API-прокси перед публикацией API см. раздел «Добавление поддержки CORS в API-прокси» .

Размер полезной нагрузки сообщения

Во избежание проблем с памятью в Edge размер полезной нагрузки сообщения ограничен 10 МБ. Превышение этого размера приводит к ошибке protocol.http.TooBigBody .

Этот вопрос также обсуждается в этом сообщении на форуме Apigee Community .

Ниже приведены рекомендуемые стратегии обработки сообщений большого размера в Edge:

  • Потоковая передача запросов и ответов. Обратите внимание, что при потоковой передаче политики больше не имеют доступа к содержимому сообщения. См. раздел «Потоковая передача запросов и ответов» .
  • В Edge for Private Cloud версии 4.15.07 и более ранних версиях отредактируйте файл http.properties обработчика сообщений, увеличив лимит в параметре HTTPResponse.body.buffer.limit . Обязательно протестируйте изменения перед развертыванием в рабочей среде.
  • В Edge for Private Cloud версии 4.16.01 и более поздних версиях запросы с полезной нагрузкой должны включать заголовок Content-Length, или, в случае потоковой передачи, заголовок "Transfer-Encoding: chunked". Для POST-запроса к API-прокси с пустой полезной нагрузкой необходимо передать Content-Length равный 0.
  • В Edge for Private Cloud версии 4.16.01 и более поздних версиях для изменения ограничений установите следующие параметры в файлах /opt/apigee/router.properties или message-processor.properties. Дополнительную информацию см. в разделе «Установка ограничения размера сообщения на маршрутизаторе или обработчике сообщений» .

    Оба параметра имеют значение по умолчанию "10m", что соответствует 10 МБ:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Обработка ошибок

  • Используйте правила обработки ошибок (FaultRules) для обработки всех ошибок. (Политики RaiseFault используются для остановки потока сообщений и отправки обработки в поток правил обработки ошибок.)
  • В потоке FaultRules используйте политики AssignMessage для формирования ответа об ошибке, а не политики RaiseFault. Условно выполняйте политики AssignMessage в зависимости от типа возникшей ошибки.
  • Всегда включает обработчик ошибок по умолчанию, позволяющий сопоставлять системные ошибки с заданными пользователем форматами ответов на запросы.
  • По возможности всегда оформляйте ответы на сообщения об ошибках в соответствии со стандартными форматами, доступными в вашей компании или проекте.
  • Используйте содержательные, понятные человеку сообщения об ошибках, предлагающие решение возникшей проблемы.

См. раздел «Обработка ошибок» .

Рекомендации по передовым отраслевым практикам см. в разделе «Проектирование RESTful-ответов на ошибки» .

Упорство

Карты ключ/значение

  • Используйте карты ключ/значение только для ограниченных наборов данных. Они не предназначены для долговременного хранения данных.
  • При использовании сопоставления ключ/значение следует учитывать производительность, поскольку эта информация хранится в базе данных Cassandra.

См. политику работы с картой ключевых значений .

Кэширование ответов

  • Не заполняйте кэш ответов, если ответ не был успешным или если запрос не является GET-запросом. Кэширование операций создания, обновления и удаления не требуется. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Заполните кэш одним согласованным типом контента (например, XML или JSON). После получения записи в responseCache преобразуйте ее в необходимый тип контента с помощью JSONtoXML или XMLToJSON. Это предотвратит хранение двойных, тройных или более повторяющихся данных.
  • Убедитесь, что ключ кэша соответствует требованиям кэширования. Во многих случаях в качестве уникального идентификатора можно использовать request.querystring .
  • Не включайте ключ API ( client_id ) в ключ кэша, если это явно не требуется. Чаще всего API, защищенные только ключом, возвращают одни и те же данные всем клиентам для одного и того же запроса. Хранить одно и то же значение для нескольких записей на основе ключа API неэффективно.
  • Установите подходящие интервалы истечения срока действия кэша, чтобы избежать некорректного чтения.
  • По возможности старайтесь, чтобы политика кэширования ответов, заполняющая кэш, выполнялась как можно позже в PostFlow ответа ProxyEndpoint. Другими словами, пусть она выполняется после этапов преобразования и медиации, включая медиацию на основе JavaScript и преобразование между JSON и XML. Кэширование обработанных данных позволяет избежать затрат на производительность, связанных с выполнением этапа медиации каждый раз при получении кэшированных данных.

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

  • Политика кэширования ответов для поиска записи в кэше должна выполняться в предварительном потоке запроса ProxyEndpoint. Избегайте реализации слишком сложной логики, за исключением генерации ключа кэша, перед возвратом записи в кэше. В противном случае преимущества кэширования будут сведены к минимуму.
  • В целом, поиск в кэше ответов следует проводить как можно ближе к моменту запроса клиента. И наоборот, заполнение кэша ответов следует проводить как можно ближе к моменту ответа клиента.
  • При использовании нескольких различных политик кэширования ответов в прокси-сервере следуйте этим рекомендациям, чтобы обеспечить различное поведение для каждой из них:
    • Выполняйте каждую политику на основе взаимоисключающих условий. Это поможет гарантировать, что будет выполнена только одна из нескольких политик кэширования ответов.
    • Для каждой политики кэширования ответов задайте разные ресурсы кэша. Ресурс кэша указывается в элементе <CacheResource> политики.

См. политику кэширования ответов .

Политика и пользовательский код

Политика или пользовательский код?

  • В первую очередь (по возможности) используйте встроенные политики. Политики Apigee усилены, оптимизированы и поддерживаются. Например, используйте стандартные политики AssignMessage и ExtractVariables вместо JavaScript (по возможности) для создания полезных нагрузок, извлечения информации из полезных нагрузок (XPath, JSONPath) и т. д.
  • JavaScript предпочтительнее Python и Java. Однако, если производительность является основным требованием, следует использовать Java вместо JavaScript.

JavaScript

  • Используйте JavaScript, если это более интуитивно понятно, чем политики Apigee (например, при установке target.url для множества различных комбинаций URI).
  • Сложный анализ полезной нагрузки, например, итерация по объекту JSON и кодирование/декодирование Base64.
  • В политике JavaScript существует ограничение по времени, поэтому бесконечные циклы блокируются.
  • Всегда используйте шаги JavaScript и размещайте файлы в папке ресурсов jsc . Тип политики JavaScript предварительно компилирует код во время развертывания.

См. раздел «Программирование API-прокси с помощью JavaScript» .

Java

  • Используйте Java, если производительность имеет наивысший приоритет или если логику невозможно реализовать на JavaScript.
  • Включайте исходные файлы Java в систему отслеживания исходного кода.

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

Python

  • Не используйте Python, если это не абсолютно необходимо. Скрипты на Python могут создавать узкие места в производительности при простом выполнении, поскольку они интерпретируются во время выполнения.

Вызовы скриптов (Java, JavaScript, Python)

  • Используйте глобальный блок try/catch или аналогичный.
  • Генерируйте осмысленные исключения и корректно перехватывайте их для использования в ответах на ошибки.
  • Выбрасывайте и перехватывайте исключения на ранних этапах. Не используйте глобальный блок try/catch для обработки всех исключений.
  • При необходимости выполняйте проверки на null и undefined. Например, это может потребоваться при получении необязательных переменных потока.
  • Избегайте выполнения HTTP/S-запросов внутри вызова скрипта. Вместо этого используйте политику Apigee ServiceCallout, поскольку она корректно обрабатывает соединения.

JavaScript

  • JavaScript на платформе API поддерживает XML через E4X .

См. объектную модель JavaScript .

Java

  • При доступе к содержимому сообщений старайтесь использовать context.getMessage() вместо context.getResponseMessage или context.getRequestMessage . Это гарантирует, что код сможет получить содержимое как в потоке запроса, так и в потоке ответа.
  • Импортируйте библиотеки в организацию или среду Apigee Edge, но не включайте их в JAR-файл. Это уменьшит размер пакета и позволит другим JAR-файлам получать доступ к тому же репозиторию библиотек.
  • Импортируйте JAR-файлы, используя API ресурсов Apigee, вместо того, чтобы включать их в папку ресурсов прокси-сервера API. Это сократит время развертывания и позволит использовать одни и те же JAR-файлы несколькими прокси-серверами API. Еще одно преимущество — изоляция загрузчика классов.
  • Не используйте Java для управления ресурсами (например, для создания и управления пулами потоков).

См. Преобразование ответа в верхний регистр с помощью вызова Java .

Python

  • Генерируйте осмысленные исключения и корректно перехватывайте их для использования в ответах Apigee на ошибки.

См. политику использования скриптов Python .

Вызовы сервисной службы

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

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

  • Создайте сообщение запроса ServiceCallout, используя политику AssignMessage, и заполните объект запроса в переменной сообщения. (Это включает в себя установку полезной нагрузки запроса, пути и метода.)
  • URL-адрес, настраиваемый в политике, требует указания протокола, то есть часть URL-адреса, отвечающая за протокол, например, https:// , не может быть указана переменной. Кроме того, необходимо использовать отдельные переменные для доменной части URL-адреса и для остальной части URL-адреса. Например: https://{domain}/{path}
  • Сохраните объект ответа для вызова службы в отдельной переменной сообщения. Затем вы можете проанализировать эту переменную сообщения, сохранив при этом исходную полезную нагрузку сообщения для использования другими политиками.

См. правила вызова сервисной службы .

Доступ к сущностям

Политика AccessEntity

  • Для повышения производительности ищите приложения по uuid , а не по названию приложения.

См. Политику доступа к сущностям .

Ведение журнала

  • Используйте единую политику syslog для всех пакетов и внутри одного пакета. Это обеспечит согласованный формат логирования.

См. политику ведения журнала сообщений .

Мониторинг

Клиентам облачной платформы не требуется проверять отдельные компоненты Apigee Edge (маршрутизаторы, обработчики сообщений и т. д.). Глобальная операционная команда Apigee тщательно отслеживает все компоненты, а также проводит проверки работоспособности API по запросам клиентов.

Apigee Analytics

Аналитические инструменты могут обеспечивать мониторинг некритичных API-интерфейсов, поскольку измеряется процент ошибок.

См. панели аналитики .

След

Инструмент трассировки в пользовательском интерфейсе управления API Edge полезен для отладки проблем API во время выполнения, как в процессе разработки, так и в процессе эксплуатации API.

См. раздел «Использование инструмента трассировки» .

Безопасность