Проектирование API и интеграция систем

Все темы Systems Analyst

Приходилось ли вам проектировать взаимодействие информационных систем?

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

Приходилось ли вам проектировать API в нотации OpenAPI/Swagger?

Расскажите о реальном опыте описания API. OpenAPI является спецификацией описания HTTP API; Swagger обозначает семейство инструментов для работы с ней. В контракте фиксируют операции, параметры, схемы данных, ответы и способы аутентификации.

Как снизить нагрузку на веб-сервис?

Существует несколько способов снижения нагрузки на вебсервис:

1. Кэширование: Хранение результатов часто запрашиваемых запросов на некоторое время для быстрого доступа.

2. Масштабирование: Распределение нагрузки между несколькими экземплярами вебсервиса (горизонтальное масштабирование) или увеличение ресурсов одного экземпляра (вертикальное масштабирование).

3. Оптимизация запросов: Улучшение структуры запросов и использование индексов в базе данных для повышения производительности запросов.

4. Асинхронные задачи: Отделение долгих или ресурсоемких операций от основного потока выполнения, чтобы основной сервис был доступен для новых запросов.

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

6. Использование CDN : Распределение статических ресурсов через Content Delivery Network для ускорения их доставки клиентам.

7. Мониторинг и оптимизация: Регулярное отслеживание и анализ нагрузки на сервер и эффективность работы вебсервиса для выявления слабых мест и возможных улучшений.

Что зафиксировать в контракте API-запроса?

Для операции фиксируют HTTP-метод и URI, path/query/header-параметры, их типы, форматы, обязательность и ограничения. Описывают схему тела, примеры и правила валидации. Контракт должен задавать механизм авторизации и требуемые права, успешные ответы, единый формат ошибок и значимые статусы. Для изменяющей операции нужны правила повторов, идемпотентности и конкурентного изменения. Также полезны лимиты, пагинация, версия и корреляционный идентификатор. OpenAPI помогает формализовать контракт, но не заменяет описание бизнес-семантики: что именно меняется и какие инварианты сохраняются.

Какие способы версионирования API выбрать?

Версию можно поместить в URI, например /v2, в заголовок, vendor media type или реже в query-параметр. URI проще видеть, маршрутизировать и документировать; заголовки и media type сохраняют стабильный адрес, но сложнее для клиентов и инфраструктуры. Выбор менее важен, чем единое правило жизненного цикла. Новую версию публикуют с описанием отличий, миграцией и сроком поддержки; старую и новую некоторое время обслуживают параллельно. Завершение версии объявляют заранее, измеряют оставшихся клиентов и только после миграции отключают. Совместимые добавления обычно не требуют новой major-версии.

Как сохранить обратную совместимость API?

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

Как сделать POST идемпотентным?

Клиент генерирует ключ одной бизнес-операции и повторяет POST с тем же Idempotency-Key. Сервер атомарно регистрирует ключ в заданной области, например аккаунт и тип операции, сохраняет отпечаток запроса, состояние обработки и результат. Параллельный повтор не должен запустить вторую операцию: это обеспечивают уникальное ограничение и транзакция либо эквивалентный механизм. Для того же ключа и тела возвращают сохранённый совместимый результат; другое тело означает конфликт. Контракт задаёт TTL, поведение состояния processing и коды ответов. Дедупликация входа не отменяет необходимость идемпотентно работать с downstream-системами.

Когда выбрать REST, а когда брокер сообщений?

REST подходит, когда инициатору нужен немедленный ответ, операция короткая, а зависимость доступна в момент вызова. Брокер полезен для асинхронной обработки, буферизации всплесков и слабой временной связанности производителей с потребителями. Но он добавляет повторы, дубли, eventual consistency, управление порядком и отдельную наблюдаемость. Выбор делают по допустимой задержке, требованию к ответу, объёму и характеру нагрузки, правилам доставки и способности потребителя создавать backpressure. Часто применяют оба подхода: API принимает команду и возвращает идентификатор, а выполнение и события идут через брокер.

Как передать слишком большой набор параметров запроса?

Сначала выясняют реальный лимит клиента, прокси и сервера: HTTP не задаёт единого максимума длины URI, его задаёт инфраструктура. Небольшой фильтр оставляют в query, потому что GET сохраняет безопасную семантику и удобно кешируется. Сложный или чувствительный фильтр можно передать в теле POST /search; это уже отдельный контракт, и обычные HTTP-кеши не обязаны обращаться с ним как с GET. Другой вариант, создать ресурс сохранённого запроса и затем читать результат по идентификатору. Тело GET использовать рискованно: у него нет общепринятой семантики, посредники и клиенты могут его игнорировать.

На каких слоях кэшировать ответ API?

Кеш можно разместить в браузере, CDN или reverse proxy, выбирая слой по тому, кто вправе разделять ответ. Cache-Control задаёт срок и режим хранения, ETag с If-None-Match позволяет перепроверить устаревший объект, Vary разделяет варианты по значимым заголовкам. Публичный неизменяемый контент хорошо подходит CDN; персональные ответы обычно требуют private, точного ключа и запрета общего кеширования чувствительных данных. Нужно заранее определить допустимую устарелость и способ инвалидирования. Кеширование не должно менять правила авторизации: попадание ответа одного пользователя другому является утечкой, а не особенностью кеша.

Чем безопасный HTTP-метод отличается от идемпотентного?

Безопасный метод по контракту предназначен только для чтения и не просит сервер изменить состояние. К безопасным относятся GET, HEAD, OPTIONS и TRACE, хотя побочные эффекты вроде логирования допустимы. Идемпотентный метод может менять состояние, но несколько одинаковых запросов должны иметь тот же задуманный итоговый эффект, что и один. PUT и DELETE идемпотентны по семантике, POST и PATCH такой гарантии по умолчанию не имеют. Идемпотентность не требует одинакового HTTP-ответа: повторный DELETE может вернуть другой статус, сохранив то же состояние ресурса.

Когда API должен вернуть 204, а когда 404?

204 No Content означает, что сервер успешно выполнил запрос и не возвращает представление. Для успешного DELETE это естественный вариант. 404 Not Found сообщает, что текущего представления ресурса нет или сервер не раскрывает его существование. Повторный DELETE может вернуть 404, хотя метод остаётся идемпотентным, либо 204, если контракт намеренно скрывает различие между удалённым и отсутствующим ресурсом. Для GET отсутствие ресурса обычно означает 404; для PATCH по отсутствующему ресурсу тоже обычно 404, если контракт не создаёт его. Главное, единая документированная семантика и формат ошибок.

Как выбрать между pull- и push-доставкой?

При pull потребитель сам запрашивает данные и регулирует темп. Это упрощает backpressure и восстановление, но интервал polling добавляет задержку и пустые запросы; курсор или offset нужны, чтобы не пропускать изменения. При push источник отправляет данные при появлении, что снижает задержку, но требует обработки недоступного или медленного потребителя, повторов и ограничения очереди. В обоих вариантах возможны дубли, а гарантии порядка зависят от протокола и ключа партиционирования. Выбор делают по допустимой задержке, объёму, сетевым ограничениям и тому, какая сторона способна хранить состояние доставки.

Почему удалённый вызов нельзя считать локальным?

Удалённый вызов проходит через сеть и другой процесс, поэтому может завершиться, зависнуть, потерять ответ или выполниться на сервере после таймаута клиента. Появляются сериализация, несовместимость версий, лимиты, авторизация и отдельные точки отказа. Нужны таймауты, ограниченные повторы только для безопасных или защищённых идемпотентностью операций, circuit breaker по ситуации и сквозная трассировка. Частичный успех нельзя представить обычным исключением локальной функции: клиент часто не знает, применился ли эффект. RPC может выглядеть как метод, REST как ресурс, но транспортная неопределённость одинакова. Контракт должен описывать ошибки и восстановление.

Что согласовать до начала разработки интеграции?

До разработки согласуют бизнес-сценарий и участников, владельца каждого набора данных и источник истины. Нужны объём, частота, допустимая задержка, порядок, правила повторов и дедупликации, поведение при частичном отказе и восстановление. Фиксируют протокол, схему, версии, ошибки, лимиты, аутентификацию, авторизацию и требования к персональным данным. Определяют среды, тестовые данные, мониторинг, корреляцию запросов, SLO и ответственных за инциденты. Контракт дополняют примерами и критериями приёмки. Если хотя бы одна сторона не понимает, как обнаружить и разобрать потерянное сообщение, интеграция ещё не готова к реализации.