Независимо от того, работаете ли вы с локальными системами, облачными решениями или сторонними сервисами, ключевые вопросы остаются одними и теми же: какой пользовательский или клиентский опыт вы хотите предложить? И как согласовать с этим опытом вашу стратегию интеграции?

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

Введение

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

Большинство обменов данными происходит локально? Тогда ваша система управления API должна находиться в локальной инфраструктуре. А если в облаке? Логика та же! Если же оба варианта — возможна гибридная архитектура, сочетающая облачные и локальные компоненты.

Об интеграции API

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

Такие сторонние API могут вызываться напрямую из браузера, с вашего корпоративного сайта или через вашу систему управления API, включая сценарии компоновки API. В случае со сторонними API особенно важно учитывать модель ценообразования и соглашения об уровне обслуживания (SLA): если вашей системе требуется SLA на уровне 99,9%, вы не можете полагаться на API, предоставляющий только 99,5%.

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

Паттерны интеграции API

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

Каждый API уникален: создание интеграций требует глубокого анализа множества нюансов — от различий между SOAP и REST, XML и JSON, до механизмов аутентификации, особенностей миграции, подходов к событиям (вебхуки или поллинг), уникальных кодов ошибок, ограниченных механизмов поиска и многого другого.

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

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

Коды ошибок

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

Паттерн: Соблюдайте коды ошибок HTTP

Поскольку большинство кодов ошибок HTTP стандартизированы в RFC, важно соблюдать эти стандарты и иметь под рукой исчерпывающий и точный список. В следующей таблице описаны основные коды ошибок HTTP, однако рекомендуется использовать полный и актуальный список, например, представленный на сайте Mozilla: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status.

Однако одного лишь знания кодов ошибок недостаточно. Пользователи не должны гадать, какие коды ошибок реализованы в вашем API. Рекомендуется документировать все ошибки прямо в спецификации — например, в файле описания API по стандарту Swagger (OpenAPI). Ниже приведён пример описания ответов, показывающий, как задокументировать коды ошибок:

responses:
   '200':
   description: OK.
   '400':
   description: Bad request. Parameter should be a string.
   '401':
   description: Authorization failed.
   '404':
   description: Not found.
   '5XX':
   description: Internal error.

Кроме того, хотя бы для целей отладки, стоит добавить структуру ошибки — то есть объект, содержащий динамическое сообщение об ошибке и её код, оформленный в виде отдельной структуры.

Responses:
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'

Гранулярность и принцип KISS

Паттерн: Делайте ваш API простым и читаемым; стремитесь к среднегранулированным ресурсам.

Гранулярность (детализация) и принцип KISS («Keep It Simple, Stupid» — «Делай проще, глупец!») работают рука об руку. Принцип KISS подсказывает вам выбрать одну стратегию по определению уровня детализации — ту, которая будет наиболее простой и понятной для конечного пользователя — разработчика, который будет использовать ваш API. Ниже приведены ключевые идеи проектирования API в соответствии с этим подходом:

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

• Сначала проработайте основные пользовательские сценарии, а затем — все остальные.

• Используйте общеупотребительные термины, а не специализированную бизнес-терминологию.

• Исходите из того, что разработчик должен иметь только один способ реализовать каждую функциональность.

С таким подходом мелко- и крупногранулированные API плохо подходят. Мелкогранулированные API требуют дополнительных усилий, но не дают ощутимой выгоды — вам придётся постоянно решать, как категоризировать ресурсы, как соотносятся между собой различные сущности и т.п., при этом результат — просто более длинные URL.

С другой стороны, слишком крупногранулированные API создают ощущение хаоса — ресурсы оказываются на одном уровне, даже если между ними нет логических связей.

Продемонстрируем это на примере зоомагазина (pet shop).

Неправильно:

//Fine grained
GET /animals/mammals/omnivores/cats

//Coarse grained
GET /cats
GET /payments

Желательно стремиться к API средней гранулярности. Как правило, ресурс API, структура которого содержит не более двух уровней, обладает подходящей степенью гранулярности.

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

GET /animals/cats

Или так:

GET /animals/42
{
   "id":"42",
   "animalType":"cat"
   "cat":
{
      "mustacheSize":"7",
      "cuteness":"maximum"
   }
}

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

URLs

Паттерн: Используйте существительные, а не глаголы; выстраивайте иерархическую структуру; соблюдайте соглашения о нейминге; указывайте версии и применяйте правильные HTTP-методы.

Единственное и множественное число существительных

В отличие от философии SOAP, принципы REST ориентированы на ресурсы, поэтому в большинстве случаев следует использовать существительные.

Правильно:

GET /orders

Неправильно:

GET /Getorders

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

Правильно:

GET /orders
GET /orders/042

Неправильно:

GET /Getorders

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

Иерархическая структура

Ваши ресурсы должны иметь структурированное представление, и вы должны использовать путь URL для получения необходимых деталей. Например, пусть у вас есть клиент, определяемый по его идентификатору, имени и адресу. Как и в объектно-ориентированном программировании, вы бы создали класс клиента, содержащий классы адресов — с API-ресурсами следует поступать аналогичным образом. В нашем примере, чтобы получить адреса клиента, необходимо обратиться по его идентификатору, а затем — по адресу:

GET /customers/042/addresses

Согласованное использование регистров

Необходимо определить свои соглашения об именовании — в частности, «политику регистров», чтобы все ресурсы использовали единообразный стиль написания. Пользователи не должны постоянно обращаться к документации, чтобы понять, какой регистр используется для конкретного ресурса. Для параметров часто применяются snake_case и camelCase. Хотя объективных причин отдавать предпочтение одному из них нет, разработчики чаще используют camelCase (популярен в Java), тогда как snake_case легче читается для неспециалистов. Для URL чаще используется spinal-case (через дефисы), так как некоторые серверы не учитывают регистр символов.

Примеры различных стилей:

• camelCase – Get /customers?countryCode=US

• snake_case – Get /customers?country_code=US

• spinal-case – Get /vip-customers

Версионирование

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

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

Пример:

GET /v1/customers
GET /v2/customers

HTTP-методы

Необходимо использовать HTTP-методы (т.е. глаголы) строго в соответствии с их назначением. Изначально HTTP был спроектирован как протокол, ориентированный на ресурсы, и каждый метод описывает конкретное действие, которое следует выполнять над ресурсом.

GET — извлекает данные о ресурсе.

Для коллекции:

GET /customers
200 OK
[{"id":"42", "name":"John Doe"},
{"id":"43", "name":"Elisa Re"}]

Для конкретного экземпляра:

GET /customers/42
200 OK
{"id":"42", "name":"John Doe"}

POST — создает новый ресурс.

Для коллекции:

POST /customers {"name":"John Doe", "countryCode":"US"}
201 Created
Location: https://myapi.com/customers/42

PUT — полностью заменяет или создает ресурс.

Для конкретного экземпляра:

PUT /customers/42 {"name":"John Si", "countryCode":"US"}
200 OK
Full replacement:
200 OK
Creation:
201 OK

PATCH — частично обновляет существующий ресурс.

Для конкретного экземпляра:

PATCH /customers/42 {"countryCode":"UK"}
200 OK

DELETE — удаляет существующий ресурс.

Для конкретного экземпляра:

DELETE /customers/42
204 OK

Аутентификация

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

Паттерн: следуйте признанным отраслевым протоколам аутентификации и идентификации в соответствии с потребностями вашего бизнеса.

API-ключи

Использование API-ключей (API Keys) все еще широко распространено и является очень популярным способом доступа к API. Это быстрый и простой способ аутентифицировать учетные записи с относительно небольшой затратой для поставщика, так как ключи можно легко создавать и удалять. API-ключ — это уникально сгенерированный набор символов (иногда случайный), который часто передается в виде пары: пользователь и секрет. Получив API-ключи, лучше всего скопировать и сохранить их в менеджере паролей и обращаться с ними, как с обычным паролем.

OAuth 2.0 и OpenID Connect

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

OAuth является предпочтительным методом аутентификации, так как позволяет пользователям определять уровень доступа, который получает интегрируемое приложение, а также устанавливать временные ограничения. Некоторые API имеют короткие сроки действия токенов, в таких случаях необходимо использовать refresh-токены. OpenID Connect — это стандартизированное расширение OAuth 2.0, добавляющее уровень нормализованной идентификации третьей стороной и идентификации пользователя. Не все поставщики API требуют его, но он рекомендуется, если необходимо реализовать тонкую настройку управления доступом и работать с несколькими поставщиками удостоверяющих данных.

Вебхуки

Вебхуки позволяют получать обновления в реальном времени, так как они основаны на push-модели, а не на pull-модели. При этом методе, когда в приложении происходят изменения, они отправляются на заранее указанный вами URL. Такой способ обновления информации позволяет приложениям реагировать в реальном времени и создавать динамичный user experience. Кроме того, это предпочтительный шаблон реализации, так как он требует только указания URL, в отличие от поллинга, при котором необходимо создать фреймворк, регулирующий частоту и объем запрашиваемой информации. Например, фреймворк для поллинга в Marketo состоит из 239 строк кода, в то время как аналогичный вебхук требует всего пять строк.

Параметры запросов (querying)

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

Мы автоматизировали перемещение данных, чтобы интеграция работала в реальном времени, но поток данных может быть избыточным — нам нужна лишь конкретная часть, актуальная для работы нашего приложения. Чтобы отфильтровать ненужные данные, необходимо использовать параметры запросов.

Querying — это последняя часть API-эндпоинта, которая направляет вызов к нужным данным:

GET /widgets?query_parameter_here

Возможность выполнять поиск как по базам данных, так и по целевым приложениям является важным шагом. Это позволяет тестировать и подтверждать полученные ответы, а также видеть различия в структуре данных между документацией и фактическими результатами. Querying позволяет изменять пары «ключ–значение» в запросе. В URL querying начинается с вопросительного знака (?), и параметры разделяются амперсандом (&).

Пример:

GET /widgets?type=best&date=yesterday

Для тестирования API существует множество инструментов в зависимости от предпочитаемого языка, но документация большинства API использует curl-команды. Чтобы протестировать API, откройте терминал и вставьте curl-команду, чтобы посмотреть ответ. Затем попробуйте изменить пары ключ–значение, чтобы получить только нужную информацию. При добавлении параметров в команду curl обязательно указывайте обратный слеш перед вопросительным знаком, так как ? и & являются специальными символами.

Настройка этих пар помогает сократить объем данных и нагрузку на ваше приложение. При тестировании можно увеличить объем данных, чтобы проверить, при каком объеме начинают возникать ошибки.

Фильтры

Для фильтрации используйте ? для указания параметра и & как разделитель:

GET /widgets?type=best&date=yesterday

Поиск

Поиск чаще всего лучше организовывать так же, как в Google Search (то есть с использованием ключевого слова search), например когда вы ищете слово "test" запрос будет выглядеть так: www.google.com/search?q=test.

Чтобы найти ресурс определённого типа:

GET /customers/search?type=vip

Чтобы найти несколько ресурсов:

GET /search?q=customers+vip

Ключевые слова: first, last и count

Используйте first, last и count, чтобы получить первый элемент, последний элемент и общее количество элементов в коллекции соответственно.

Сортировка

Важным элементом получения нужной информации является то, как она будет представлена. Это особенно полезно при тестировании и отображении данных в интерфейсе пользователя. Многие API поддерживают параметры sort, sort_by или order в URL, чтобы изменить порядок данных (по возрастанию или убыванию). Например: GET /widgets?sort_by=desc(created). Этот запрос вернет самые свежие виджеты на складе.

Пагинация

Паттерн: используйте методы пагинации для веб-интерфейсов и мобильных приложений.

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

Частичный возврат данных (Partial Response)

В некоторых случаях нет необходимости получать все поля, определяющие объект. Частичные возраты данных особенно полезны в мобильных сценариях, где приоритетом является экономия трафика. Используйте параметр fields, чтобы получить только нужные поля:

GET /customers/42?fields=name,status
200 OK
{"name":"John Doe", "status":"VIP"}

Смещение (Offset)

Это самый простой и потому часто используемый метод. LIMIT задаёт количество возвращаемых строк, а OFFSET — начальную точку. Например, запрос /widgets?limit=10 вернет 10 строк для первой страницы. Вторая страница будет /widgets?limit=10&offset=10, что вернет следующие 10 строк, начиная с 10-й. Недостаток этого подхода — снижение производительности при работе с большими объёмами данных: при offset = 1 000 000 API всё равно должно пройти через миллион строк, прежде чем вернуть нужные.

Пагинация по ключу (Keyset)

Keyset-пагинация помогает избежать проблем с большими объемами данных, используя значение последнего элемента предыдущей страницы как точку отсчета для следующей. Пример: Первый запрос: GET /widgets?limit=10 с уникальным идентификатором таким как дата создания или изменения. Второй: GET /widgets?limit=10&created:lte:2019-09, следующий: GET /widgets?limit=10&created:lte:2019-10 и так далее.

Фиксированные страницы (Fixed Data Pages)

Простой способ: в параметрах запроса указывается нужная страница. Например, чтобы получить четвертую страницу: GET /widgets?page=4. Этот метод удобен, если приложение, с которым вы работаете, имеет заранее определённые страницы и вы хотите получать данные последовательно. Однако его сложнее применять, если неизвестно, что находится на конкретной странице.

Гибкие страницы (Flexible Data Pages)

Похож на предыдущий способ, но дополнительно позволяет задать размер страницы. Например: GET /widgets?page=4&page_size=25 позволяет более точно настроить получаемую страницу. Это особенно полезно при создании интерфейсов, где важно контролировать объем возвращаемых данных.

Массовая передача данных (Bulk)

До этого момента API-интеграция касалась работы с отдельными наборами данных, но что делать, если нужно переместить большой объем данных между системами? Некоторые приложения предоставляют такую возможность через Bulk API. Bulk API позволяет массово обновлять, вставлять и удалять записи. Это особенно полезно при миграции больших систем (например, маркетинговой автоматизации, CRM или ERP) от одного поставщика к другому.

Паттерн: используйте массовую передачу данных при работе с большими объемами.

Bulk API обрабатывает данные пакетами: при отправке запроса на массовую операцию поставщик приложений возвращает идентификатор задачи и асинхронно отправляет пакеты данных до завершения операции. В зависимости от размера данных можно отслеживать статус задания по уникальному идентификатору и закрыть задание после завершения. Обратите внимание на поддерживаемые форматы данных — CSV, JSON или XML. Также проверьте лимиты API, так как при передаче больших объемов данных можно легко их превысить.

SDK

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

Паттерн: предоставьте SDK, чтобы упростить работу разработчиков с вашим API.

Кроме того, SDK может обеспечить шифрование данных и выполнение требований безопасности (например, для хранения паролей). В медицине и финансовой сфере SDK помогает соблюдать нормативные требования.

Некоторые рекомендации по разработке SDK:

• Объединяйте запросы в пакеты, отправляя их одним HTTP-вызовом — установление соединений требует значительных ресурсов. Вы можете создать систему очередей на случай, если вам не обязательно, чтобы запросы приходили одновременно.

• Сжимайте полезную нагрузку (payload) — это легко забыть при вызове API, поэтому лучше не забывать про это и в SDK.

• Добавляйте заголовок User-Agent с номером версии SDK и используемым языком — это поможет отслеживать использование новых версий.

• Настройте аналитику API — чтобы отслеживать производительность и улучшать SDK.

• Поддерживайте популярные языки программирования, используемые вашей целевой аудиторией.

• Детально документируйте SDK, включая журнал изменений и параметры конфигурации.

Заключение

Когда организации внедряют описанные интеграционные паттерны, следующий шаг — это качественное управление API. Обычно оно реализуется как дополнительный слой над существующими API и позволяет внедрять более строгие меры безопасности и управления, обеспечивая лучший контроль над тем, кто и как использует API. Такие практики включают: ограничение числа запросов за определенный период (rate limiting), модификацию тел запросов/ответов (traffic shaping), расширенную аутентификацию и авторизацию, публикацию API в портале для разработчиков, повышение прозрачности с помощью мониторинга и аналитики.

Дополнительная литература

Richardson, L. & Amundsen, M. (2015). RESTful web APIs. O'Reilly.

Biehl, M. (2016). RESTful API design. CreateSpace.

Louvel, J. (2013). Restlet in action: Developing RESTful web APIs in Java. Manning.

Kalali, M. & Mehta, B. (2013). Developing RESTful services with JAX‑RS 2.0, WebSockets, and JSON. Packt Publishing.

Jacobson, D., Brail, G. & Woods, D. (2011). APIs: A strategy guide. O'Reilly.

Lauret, A. (2019). The design of web APIs. Manning.

Higginbotham, J. (2021). Principles of web API design: Delivering value with APIs and microservices. Addison‑Wesley Professional.

Оригинал статьи