Какие форматы для передачи сообщений использует REST?

Форматы для передачи сообщений в REST

REST API использует различные форматы для передачи данных между клиентом и сервером. Это одно из ключевых знаний для Business Analyst, работающего над API интеграциями. Расскажу о каждом формате, когда его использовать, и какие плюсы и минусы у каждого.

JSON — стандарт современного REST

Это наиболее популярный формат в современных REST API.

Структура:

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "active": true,
  "roles": ["admin", "user"]
}

Преимущества:

• Компактность — меньше данных передаётся по сети, чем в XML
• Встроенная типизация — JSON поддерживает числа, строки, булевы значения, массивы, объекты
• Читаемость — относительно легко читать и понимать для человека
• JavaScript-native — родной формат для JavaScript и браузеров
• Универсальность — поддерживается всеми современными языками программирования
• API стандарт — практически все современные API используют JSON

Недостатки:

• Отсутствие комментариев — нельзя добавить пояснения прямо в данные
• Нет пространств имён — может быть конфликт имён полей

Когда использовать: Практически всегда в современных API.

XML — формат старого поколения

Используется в legacy системах и некоторых специализированных сценариях.

Структура:

<?xml version="1.0"?>
<user>
  <id>123</id>
  <name>John Doe</name>
  <email>john@example.com</email>
  <active>true</active>
  <roles>
    <role>admin</role>
    <role>user</role>
  </roles>
</user>

Преимущества:

• Валидация через XSD — можно определить схему и автоматически валидировать
• Namespace поддержка — избегаются конфликты имён
• Комментарии — поддерживаются встроенные комментарии
• Стандартизированность — существует очень давно, хорошо изучена

Недостатки:

• Громоздкость — намного больше данных, чем JSON
• Медленнее парсируется — требует больше обработки
• Менее удобен для веб — JSON лучше подходит для фронтенда

Когда использовать:

• В SOAP сервисах (которые иногда встречаются в интеграциях)
• В legacy системах
• Когда нужна строгая валидация через XSD

Form Data (application/x-www-form-urlencoded)

Традиционный формат HTML форм.

Структура:

name=John+Doe&email=john@example.com&active=true

Преимущества:

• Поддержка браузерами — любой браузер может отправить форму
• Простота — быстро написать
• Безопасность в URL — если нет конфиденциальных данных, можно в URL

Недостатки:

• Нет структурирования — сложно передать вложенные данные
• Ограничение размера — URL имеет максимальную длину
• Нет поддержки файлов — нужно использовать multipart/form-data для файлов

Когда использовать:

• Для простых форм в браузере
• Для GET запросов с параметрами
• Для login форм

Multipart/form-data — для файлов

Используется для передачи файлов и смешанных данных.

Структура:

--boundary123
Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: image/jpeg

[binary file data]
--boundary123
Content-Disposition: form-data; name="description"

My photo
--boundary123--

Преимущества:

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

Недостатки:

• Сложнее парсировать — требует специальной обработки
• Больше данных — boundaries и headers добавляют размер
• Медленнее — особенно на больших файлах

Когда использовать:

• Загрузка файлов (фото, видео, документы)
• Отправка аватарок
• Передача бинарных данных

Plain Text

Просто текст без структурирования.

Структура:

My simple text message

Преимущества:

• Максимальная простота — просто текст
• Минимальный размер — нет лишних данных

Недостатки:

• Отсутствие структуры — сложно парсировать структурированные данные
• Ограниченность — подходит только для простых сценариев

Когда использовать:

• CSV файлы
• Логи
• Простые текстовые сообщения

CSV (Comma-Separated Values)

Формат для табличных данных.

Структура:

id,name,email,active
1,John Doe,john@example.com,true
2,Jane Smith,jane@example.com,false

Преимущества:

• Совместимость с Excel — легко открыть в Excel
• Компактность — минимальный размер данных
• Простота — легко парсировать

Недостатки:

• Отсутствие типизации — всё текст
• Проблемы с кавычками и запятыми — нужно экранировать
• Нет вложенных данных — только плоская структура

Когда использовать:

• Экспорт данных
• Импорт bulk данных
• Интеграция с Excel

Protocol Buffers (Protobuf) — для микросервисов

Современный бинарный формат от Google.

Преимущества:

• Компактность — намного меньше JSON
• Быстрота — быстрее парсируется
• Версионирование — хорошо работает с обновлениями
• Типизация — строгая типизация

Недостатки:

• Нечитаемость — бинарный формат, нельзя открыть в текстовом редакторе
• Специфичность — нужны специальные инструменты

Когда использовать:

• В микросервисах
• Когда важна производительность
• gRPC API

MessagePack — компактный JSON

Как JSON, но компактнее и быстрее.

Преимущества:

• Компактнее JSON — меньше данных
• Быстрее JSON — быстрее парсируется
• Как JSON — интуитивная структура

Недостатки:

• Менее популярен — не все инструменты поддерживают
• Нечитаемость — бинарный формат

Когда использовать:

• Когда нужна экономия трафика
• Real-time системы

Content-Type в HTTP заголовках

Как клиент говорит серверу, в каком формате он отправляет данные:

Content-Type: application/json
Content-Type: application/xml
Content-Type: application/x-www-form-urlencoded
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary
Content-Type: text/plain
Content-Type: text/csv
Content-Type: application/protobuf

Выбор формата для REST API

Как аналитик, я руководствуюсь:

1. JSON по умолчанию — это стандарт, используй JSON если нет причин для другого
2. Файлы → multipart/form-data
3. Табличные данные → CSV
4. Legacy системы → может потребоваться XML
5. Высокопроизводительные системы → Protobuf или MessagePack
6. Простые браузерные формы → application/x-www-form-urlencoded

Практический пример

В одном API я часто комбинирую форматы:

• Запрос на создание пользователя → JSON
• Загрузка аватара → multipart/form-data
• Экспорт списка пользователей → CSV
• Интеграция с legacy SOAP → XML

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