--- title: Проектирование API и интеграция систем questionDates: q-transfer-0342: '2026-10-01' q-transfer-0343: '2026-10-01' q-transfer-0344: '2026-10-01' q-transfer-0345: '2026-10-01' q-transfer-0346: '2026-10-01' q-transfer-0360: '2026-10-01' q-transfer-0361: '2026-10-01' q-transfer-0362: '2026-10-01' q-transfer-0363: '2026-10-01' q-transfer-0364: '2026-10-01' q-transfer-0365: '2026-10-01' q-transfer-0366: '2026-10-01' seo: description: >- Тема «Проектирование API и интеграция систем» для собеседования Systems Analyst. Приходилось ли вам проектировать взаимодействие информационных систем? Приходилось ли вам проектировать API в нотации OpenAPI/Swagger? title: Проектирование API и интеграция систем — Systems Analyst --- [Все темы Systems Analyst](/prep/systems-analyst) ## Приходилось ли вам проектировать взаимодействие информационных систем? [#q-14bee738d69b8149a229e30302cd98b3] Если проектировали интеграцию, опишите реальный кейс: участников, протокол, контракт данных, обработку ошибок и свои решения. Если опыта нет, можно объяснить подход, не выдавая его за выполненный проект. :::note[Ссылки для изучения] 1. [Как аналитику работать с задачами на интеграции](https://habr.com/ru/articles/735332/) ::: --- ## Приходилось ли вам проектировать API в нотации OpenAPI/Swagger? [#q-14bee738d69b81e5bdf9c9327612a64f] Расскажите о реальном опыте описания API. OpenAPI является спецификацией описания HTTP API; Swagger обозначает семейство инструментов для работы с ней. В контракте фиксируют операции, параметры, схемы данных, ответы и способы аутентификации. :::note[Ссылки для изучения] 1. [Описание HTTP API в OpenAPI 3.0: операции, схемы, ответы и Bearer-аутентификация](https://habr.com/ru/companies/first/articles/973186/) 2. [OpenAPI и Swagger для контракта API. Ulbi TV, с 26:32](https://www.youtube.com/watch?v=XaTwnKLQi4A&t=1592s) ::: --- ## Как снизить нагрузку на веб-сервис? [#q-14bee738d69b811fb3e7c389d9c20575] Существует несколько способов снижения нагрузки на вебсервис: 1. Кэширование: Хранение результатов часто запрашиваемых запросов на некоторое время для быстрого доступа. 1. Масштабирование: Распределение нагрузки между несколькими экземплярами вебсервиса (горизонтальное масштабирование) или увеличение ресурсов одного экземпляра (вертикальное масштабирование). 1. Оптимизация запросов: Улучшение структуры запросов и использование индексов в базе данных для повышения производительности запросов. 1. Асинхронные задачи: Отделение долгих или ресурсоемких операций от основного потока выполнения, чтобы основной сервис был доступен для новых запросов. 1. Оптимизация ресурсов: Уменьшение размера передаваемых данных, улучшение алгоритмов обработки данных и минимизация использования ресурсов на сервере. 1. Использование CDN : Распределение статических ресурсов через Content Delivery Network для ускорения их доставки клиентам. 1. Мониторинг и оптимизация: Регулярное отслеживание и анализ нагрузки на сервер и эффективность работы вебсервиса для выявления слабых мест и возможных улучшений. :::note[Ссылки для изучения] 1. [Пагинация, выбор полей и асинхронные операции API — Microsoft](https://learn.microsoft.com/ru-ru/azure/architecture/best-practices/api-design) 1. [HTTP-кеширование: браузер, прокси, Cache-Control и валидация — MDN](https://developer.mozilla.org/ru/docs/Web/HTTP/Guides/Caching) ::: --- ## Что зафиксировать в контракте API-запроса? [#q-transfer-0342] Для операции фиксируют HTTP-метод и URI, path/query/header-параметры, их типы, форматы, обязательность и ограничения. Описывают схему тела, примеры и правила валидации. Контракт должен задавать механизм авторизации и требуемые права, успешные ответы, единый формат ошибок и значимые статусы. Для изменяющей операции нужны правила повторов, идемпотентности и конкурентного изменения. Также полезны лимиты, пагинация, версия и корреляционный идентификатор. OpenAPI помогает формализовать контракт, но не заменяет описание бизнес-семантики: что именно меняется и какие инварианты сохраняются. :::note[Ссылки для изучения] 1. [Параметры, тело, схемы, ответы и безопасность HTTP API в OpenAPI 3.0](https://habr.com/ru/companies/first/articles/973186/) 2. [OpenAPI и Swagger для контракта API. Ulbi TV, с 26:32](https://www.youtube.com/watch?v=XaTwnKLQi4A&t=1592s) ::: --- ## Какие способы версионирования API выбрать? [#q-transfer-0343] Версию можно поместить в URI, например `/v2`, в заголовок, vendor media type или реже в query-параметр. URI проще видеть, маршрутизировать и документировать; заголовки и media type сохраняют стабильный адрес, но сложнее для клиентов и инфраструктуры. Выбор менее важен, чем единое правило жизненного цикла. Новую версию публикуют с описанием отличий, миграцией и сроком поддержки; старую и новую некоторое время обслуживают параллельно. Завершение версии объявляют заранее, измеряют оставшихся клиентов и только после миграции отключают. Совместимые добавления обычно не требуют новой major-версии. :::note[Ссылки для изучения] 1. [Версионирование API: URI, query-параметры, заголовки и vendor media type — Microsoft](https://learn.microsoft.com/ru-ru/azure/architecture/best-practices/api-design#implement-versioning) ::: --- ## Как сохранить обратную совместимость API? [#q-transfer-0344] В текущей версии безопаснее добавлять необязательные поля и новые операции, сохраняя прежнюю семантику. Ломающими обычно будут удаление или переименование поля, смена типа, усиление обязательности, новый смысл существующего значения, сужение допустимых данных и изменение кодов или формата ошибок, на которые опираются клиенты. Даже добавление поля может сломать строгий десериализатор, поэтому совместимость проверяют контрактными тестами на поддерживаемых клиентах. Устаревшее поведение помечают как deprecated, публикуют замену и срок миграции, наблюдают использование. Если сохранить контракт нельзя, выпускают новую версию и поддерживают переходный период. :::note[Ссылки для изучения] 1. [Эволюция API: совместимое добавление полей и ломающие изменения — Microsoft](https://learn.microsoft.com/ru-ru/azure/architecture/best-practices/api-design#implement-versioning) 2. [Версионирование и совместимость API. Ulbi TV, с 25:15](https://www.youtube.com/watch?v=XaTwnKLQi4A&t=1515s) ::: --- ## Как сделать POST идемпотентным? [#q-transfer-0345] Клиент генерирует ключ одной бизнес-операции и повторяет `POST` с тем же `Idempotency-Key`. Сервер атомарно регистрирует ключ в заданной области, например аккаунт и тип операции, сохраняет отпечаток запроса, состояние обработки и результат. Параллельный повтор не должен запустить вторую операцию: это обеспечивают уникальное ограничение и транзакция либо эквивалентный механизм. Для того же ключа и тела возвращают сохранённый совместимый результат; другое тело означает конфликт. Контракт задаёт TTL, поведение состояния `processing` и коды ответов. Дедупликация входа не отменяет необходимость идемпотентно работать с downstream-системами. :::note[Ссылки для изучения] 1. [Идемпотентный POST: ключ операции, повторный результат и срок хранения — пример API ЮKassa](https://yookassa.ru/developers/using-api/interaction-format) ::: --- ## Когда выбрать REST, а когда брокер сообщений? [#q-transfer-0346] REST подходит, когда инициатору нужен немедленный ответ, операция короткая, а зависимость доступна в момент вызова. Брокер полезен для асинхронной обработки, буферизации всплесков и слабой временной связанности производителей с потребителями. Но он добавляет повторы, дубли, eventual consistency, управление порядком и отдельную наблюдаемость. Выбор делают по допустимой задержке, требованию к ответу, объёму и характеру нагрузки, правилам доставки и способности потребителя создавать backpressure. Часто применяют оба подхода: API принимает команду и возвращает идентификатор, а выполнение и события идут через брокер. :::note[Ссылки для изучения] 1. [Синхронный API или асинхронные сообщения: задержка, буферизация и сложность — Microsoft](https://learn.microsoft.com/ru-ru/azure/architecture/microservices/design/interservice-communication) ::: --- ## Как передать слишком большой набор параметров запроса? [#q-transfer-0360] Сначала выясняют реальный лимит клиента, прокси и сервера: HTTP не задаёт единого максимума длины URI, его задаёт инфраструктура. Небольшой фильтр оставляют в query, потому что `GET` сохраняет безопасную семантику и удобно кешируется. Сложный или чувствительный фильтр можно передать в теле `POST /search`; это уже отдельный контракт, и обычные HTTP-кеши не обязаны обращаться с ним как с `GET`. Другой вариант, создать ресурс сохранённого запроса и затем читать результат по идентификатору. Тело `GET` использовать рискованно: у него нет общепринятой семантики, посредники и клиенты могут его игнорировать. :::note[Ссылки для изучения] 1. [Длинные фильтры, GET с телом и POST /search: ограничения HTTP](https://habr.com/ru/articles/1055310/) ::: --- ## На каких слоях кэшировать ответ API? [#q-transfer-0361] Кеш можно разместить в браузере, CDN или reverse proxy, выбирая слой по тому, кто вправе разделять ответ. `Cache-Control` задаёт срок и режим хранения, `ETag` с `If-None-Match` позволяет перепроверить устаревший объект, `Vary` разделяет варианты по значимым заголовкам. Публичный неизменяемый контент хорошо подходит CDN; персональные ответы обычно требуют `private`, точного ключа и запрета общего кеширования чувствительных данных. Нужно заранее определить допустимую устарелость и способ инвалидирования. Кеширование не должно менять правила авторизации: попадание ответа одного пользователя другому является утечкой, а не особенностью кеша. :::note[Ссылки для изучения] 1. [Слои HTTP-кеша, приватные ответы и проверка свежести — MDN](https://developer.mozilla.org/ru/docs/Web/HTTP/Guides/Caching) ::: --- ## Чем безопасный HTTP-метод отличается от идемпотентного? [#q-transfer-0362] Безопасный метод по контракту предназначен только для чтения и не просит сервер изменить состояние. К безопасным относятся `GET`, `HEAD`, `OPTIONS` и `TRACE`, хотя побочные эффекты вроде логирования допустимы. Идемпотентный метод может менять состояние, но несколько одинаковых запросов должны иметь тот же задуманный итоговый эффект, что и один. `PUT` и `DELETE` идемпотентны по семантике, `POST` и `PATCH` такой гарантии по умолчанию не имеют. Идемпотентность не требует одинакового HTTP-ответа: повторный `DELETE` может вернуть другой статус, сохранив то же состояние ресурса. :::note[Ссылки для изучения] 1. [Безопасность и идемпотентность HTTP-методов: различие семантики](https://habr.com/ru/articles/1010240/) ::: --- ## Когда API должен вернуть 204, а когда 404? [#q-transfer-0363] `204 No Content` означает, что сервер успешно выполнил запрос и не возвращает представление. Для успешного `DELETE` это естественный вариант. `404 Not Found` сообщает, что текущего представления ресурса нет или сервер не раскрывает его существование. Повторный `DELETE` может вернуть `404`, хотя метод остаётся идемпотентным, либо `204`, если контракт намеренно скрывает различие между удалённым и отсутствующим ресурсом. Для `GET` отсутствие ресурса обычно означает `404`; для `PATCH` по отсутствующему ресурсу тоже обычно `404`, если контракт не создаёт его. Главное, единая документированная семантика и формат ошибок. :::note[Ссылки для изучения] 1. [Ответ DELETE: 204 после удаления и 404 при отсутствии ресурса — Microsoft](https://learn.microsoft.com/ru-ru/azure/architecture/best-practices/api-design) ::: --- ## Как выбрать между pull- и push-доставкой? [#q-transfer-0364] При pull потребитель сам запрашивает данные и регулирует темп. Это упрощает backpressure и восстановление, но интервал polling добавляет задержку и пустые запросы; курсор или offset нужны, чтобы не пропускать изменения. При push источник отправляет данные при появлении, что снижает задержку, но требует обработки недоступного или медленного потребителя, повторов и ограничения очереди. В обоих вариантах возможны дубли, а гарантии порядка зависят от протокола и ключа партиционирования. Выбор делают по допустимой задержке, объёму, сетевым ограничениям и тому, какая сторона способна хранить состояние доставки. :::note[Ссылки для изучения] 1. [Pull вместо push: контроль темпа чтения и long polling на примере Kafka — Arenadata](https://habr.com/ru/companies/arenadata/articles/1085972/) ::: --- ## Почему удалённый вызов нельзя считать локальным? [#q-transfer-0365] Удалённый вызов проходит через сеть и другой процесс, поэтому может завершиться, зависнуть, потерять ответ или выполниться на сервере после таймаута клиента. Появляются сериализация, несовместимость версий, лимиты, авторизация и отдельные точки отказа. Нужны таймауты, ограниченные повторы только для безопасных или защищённых идемпотентностью операций, circuit breaker по ситуации и сквозная трассировка. Частичный успех нельзя представить обычным исключением локальной функции: клиент часто не знает, применился ли эффект. RPC может выглядеть как метод, REST как ресурс, но транспортная неопределённость одинакова. Контракт должен описывать ошибки и восстановление. :::note[Ссылки для изучения] 1. [Сбои удалённых вызовов: потерянный ответ, повторы и circuit breaker — Microsoft](https://learn.microsoft.com/ru-ru/azure/architecture/microservices/design/interservice-communication) ::: --- ## Что согласовать до начала разработки интеграции? [#q-transfer-0366] До разработки согласуют бизнес-сценарий и участников, владельца каждого набора данных и источник истины. Нужны объём, частота, допустимая задержка, порядок, правила повторов и дедупликации, поведение при частичном отказе и восстановление. Фиксируют протокол, схему, версии, ошибки, лимиты, аутентификацию, авторизацию и требования к персональным данным. Определяют среды, тестовые данные, мониторинг, корреляцию запросов, SLO и ответственных за инциденты. Контракт дополняют примерами и критериями приёмки. Если хотя бы одна сторона не понимает, как обнаружить и разобрать потерянное сообщение, интеграция ещё не готова к реализации. :::note[Ссылки для изучения] 1. [Что уточнить при проектировании интеграции: сценарии, данные и контракт внешней системы — Maxilect](https://habr.com/ru/companies/maxilect/articles/592533/) :::