Экспорт и импорт данных через API: форматы, лимиты и лучшие практики

Представьте ситуацию: вам нужно перенести миллион записей из старой CRM в новую. Вы открываете документацию к API и видите строку «Limit: 100 requests per minute». Если вы просто начнете слать запросы подряд, то через минуту получите ошибку 429 Too Many Requests. Знакомая история? В мире интеграций это классика. Понимание того, как устроены лимиты API и какие форматы данных лучше использовать, экономит недели работы и нервов.

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

Основные форматы передачи данных

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

• JSON is a lightweight data interchange format that is easy for humans to read and write and easy for machines to parse and generate. Это стандарт де-факто для современных REST API. Он поддерживает вложенные структуры, что удобно для сложных объектов, таких как пользователи со списками заказов или товары с характеристиками. Минус? Для простых табличных данных он тяжелее, чем другие форматы, из-за повторяющихся ключей.
• CSV is a plain text file format that uses commas to separate values in a table. Идеален для массового импорта и экспорта больших объемов структурированных данных. Файл весит меньше JSON примерно на 30-50%, так как отсутствуют имена полей в каждой строке. Однако CSV плохо справляется с вложенными структурами - если у вас есть список тегов внутри записи, вам придется либо сериализовать его в JSON внутри ячейки, либо использовать другой разделитель.
• XML is a markup language used to encode documents in a format that is both human-readable and machine-readable. Исторически значимый формат, который все еще встречается в банковских системах, государственных порталах и некоторых ERP-системах. Он более громоздкий, чем JSON, но предлагает строгую типизацию через XSD-схемы. Если вы интегрируетесь с легаси-системой, скорее всего, вам предстоит иметь дело именно с ним.

Как выбрать? Если API позволяет выбор, используйте JSON для операций с отдельными сущностями (CRUD) и CSV для пакетной загрузки тысяч строк. XML оставьте для случаев, когда провайдер навязывает его.

Разбираемся с лимитами (Rate Limits)

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

1. Ограничение по времени (Time-based): Например, «1000 запросов в час». Это самый простой тип. Вам нужно вести счетчик и сбрасывать его каждый час. Простой алгоритм: храните timestamp последнего сброса и количество использованных токенов.
2. Алгоритм «Движущегося окна» (Sliding Window): Более сложный вариант. Сервер учитывает не только текущий период, но и предыдущие. Например, если лимит 60 запросов в минуту, и вы отправили 50 в последние 30 секунд, а затем 10 в следующие 30, вы упретесь в потолок, даже если технически прошло меньше минуты с начала часа. Такой подход честнее, но сложнее для реализации на клиенте.

Как узнать свой текущий статус? Почти все современные API возвращают заголовки ответа, такие как X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Всегда читайте эти заголовки. Если осталось 5 запросов, имеет смысл сделать паузу перед следующей партией данных, а не ждать ошибки 429.

Стратегии обработки больших объемов данных

Если вам нужно экспортировать 100 000 пользователей, отправлять их одним запросом - плохая идея. Таймауты, переполнение буфера памяти и нестабильность сети могут все испортить. Правильный подход - пагинация.

Существует два основных способа пагинации:

1. По номеру страницы (Offset/Limit): Вы передаете параметры ?page=1&limit=100. Просто и понятно. Но есть подвох: если во время экспорта кто-то добавляет новые записи, они могут «съехать» в следующую страницу, и вы можете пропустить данные или получить дубликаты. Хорошо работает для статичных датасетов.
2. По курсору (Cursor-based): Сервер возвращает специальный токен (курсор), который указывает на позицию в базе данных. Вы передаете этот токен в следующем запросе: ?cursor=abc123. Этот метод устойчив к изменениям данных в процессе чтения. Он идеален для лент новостей, чатов и больших экспортов, где данные постоянно обновляются.

Для импорта больших файлов часто используют механизм «Batch Upload». Вы загружаете один большой файл (например, ZIP с CSV), получаете ID задачи и периодически опрашиваете статус этой задачи через endpoint /jobs/{id}/status. Это снимает нагрузку с основного канала связи.

Обработка ошибок и повторные попытки

Сеть ненадежна. Запрос может зависнуть, сервер может вернуть временную ошибку 500 Internal Server Error или 503 Service Unavailable. Ваша система должна быть готова к этому.

Здесь приходит на помощь паттерн «Exponential Backoff» (экспоненциальная задержка). Логика проста: 1. Первая попытка неудачна -> ждем 1 секунду. 2. Вторая попытка неудачна -> ждем 2 секунды. 3. Третья попытка неудачна -> ждем 4 секунды. 4. И так далее, пока не достигнем максимума (например, 30 секунд).

Важно добавлять небольшой рандомизированный шум (Jitter) к задержкам. Если 10 клиентов одновременно упали в ошибку и начали повторять запросы строго каждые 2 секунды, они создадут новый всплеск нагрузки на сервере. Рандомизация распределяет запросы во времени.

Не забывайте про идемпотентность. Если вы отправляете POST-запрос на создание заказа и получили таймаут, не факт, что заказ не создался. Повторная отправка может создать дубль. Чтобы этого избежать, генерируйте уникальный идентификатор для каждого действия (Idempotency Key) и передавайте его в заголовке. Сервер запомнит этот ключ и вернет результат первой успешной операции при повторном обращении.

Практические советы для разработки интеграций

Теория хороша, но практика показывает, что большинство проблем возникает из-за мелочей. Вот несколько правил, которые спасут ваш проект:

• Логируйте все: Сохраняйте не только тело ответа, но и заголовки. Часто причина ошибки кроется в неверном Content-Type или отсутствии Authorization-токена.
• Используйте таймауты: Никогда не ждите ответа бесконечно. Установите таймаут подключения (connect timeout) на 5-10 секунд и таймаут чтения (read timeout) на 30-60 секунд. Если сервер молчит дольше - считайте, что связь потеряна.
• Версионирование API: Следите за версиями API. Поле, которое было обязательным в версии v1, может стать необязательным или переименованным в v2. Всегда указывайте версию в URL или заголовках, если это поддерживается.
• Тестирование на песочнице: Большинство провайдеров предоставляют тестовые окружения (Sandbox). Проверяйте свою логику там, прежде чем трогать продакшн-данные. Особенно это касается лимитов - в песочнице они часто отличаются от реальных.

Интеграции - это мост между двумя мирами. Чем лучше вы понимаете ограничения этого моста (форматы, лимиты, протоколы), тем стабильнее будет ваше приложение. Не бойтесь читать сырую документацию и смотреть примеры ответов в Postman или curl. Это лучший способ понять, как именно ведет себя конкретный API.