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

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

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

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

Стандарты разработки

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

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

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

Кодирование в стиле Framework предполагает хранение ресурсов прокси-сервера 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 для файлов Java JAR.
  • Имена переменных должны быть согласованными. Если вы выберете стиль, например CamelCase или Under_score, используйте его во всем прокси-сервере API.
  • По возможности используйте префиксы переменных, чтобы упорядочить переменные в зависимости от их назначения, например Consumer.username и Consumer.password .

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

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

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

Включение CORS

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

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

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

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

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

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

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

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

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

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

  • Используйте FaultRules для обработки всех ошибок. (Политики RaiseFault используются для остановки потока сообщений и отправки обработки в поток FaultRules.)
  • В потоке 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.
  • Установите соответствующие интервалы истечения срока действия кэша, чтобы избежать грязного чтения.
  • По возможности старайтесь, чтобы политика кэширования ответов, заполняющая кэш, выполнялась в ответе ProxyEndpoint PostFlow как можно позже. Другими словами, он должен выполняться после этапов трансляции и посредничества, включая посредничество на основе JavaScript и преобразование между JSON и XML. Кэшируя переданные данные, вы избегаете затрат производительности, связанных с выполнением шага передачи каждый раз, когда вы извлекаете кэшированные данные.

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

  • Политика кэширования ответов для поиска записи кэша должна присутствовать в запросе ProxyEndpoint PreFlow. Избегайте реализации слишком большого количества логики, кроме генерации ключей кэша, перед возвратом записи кэша. В противном случае преимущества кэширования сводятся к минимуму.
  • В общем, вы всегда должны выполнять поиск в кэше ответов как можно ближе к клиентскому запросу. И наоборот, вам следует поддерживать заполнение кэша ответов как можно ближе к ответу клиента.
  • При использовании нескольких разных политик кэширования ответов в прокси-сервере следуйте этим рекомендациям, чтобы обеспечить дискретное поведение каждой из них:
    • Выполняйте каждую политику на основе взаимоисключающих условий. Это поможет гарантировать, что будет выполняться только одна из нескольких политик кэширования ответов.
    • Определите разные ресурсы кэша для каждой политики кэширования ответов. Ресурс кэша указывается в элементе <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, если производительность имеет высший приоритет или если логика не может быть реализована на JavaScript.
  • Включите исходные файлы Java в отслеживание исходного кода.

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

Питон

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

Выноски сценариев (Java, JavaScript, Python)

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

JavaScript

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

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

Ява

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

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

Питон

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

См. политику Python Script .

СервисВыноски

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

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

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

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

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

Политика AccessEntity

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

См. политику объекта доступа .

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

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

См. политику регистрации сообщений .

Мониторинг

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

Апигей Аналитика

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

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

След

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

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

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