Формати даних: JSON, XML, TOML та бінарні формати

1. Проблема: Як передати об'єкт по мережі?

Уявімо, що наш сервіс замовлення кави обробляє запит і формує об'єкт у пам'яті:

var order = new
{
    Id = 42,
    Recipe = "lungo",
    Volume = "300ml",
    Price = new { Amount = 10.23m, Currency = "UAH" },
    CreatedAt = DateTime.UtcNow
};

Цей об'єкт живе у пам'яті .NET-процесу. Але клієнт — мобільний додаток на Swift або Kotlin — працює в абсолютно іншому середовищі. Він не може прочитати пам'ять .NET.

Потрібен спосіб перетворити об'єкт у послідовність байтів (або символів), яку можна:

1. Передати по мережі (через HTTP).
2. Прочитати на іншому боці, в іншій мові програмування.
3. Відновити до структури даних нативної для тієї мови.

Цей процес називається серіалізація (Serialization) — перетворення об'єкта у формат для передачі — та десеріалізація (Deserialization) — зворотне відновлення.

graph LR
    A["C# об'єкт<br/>{ Id = 42, Recipe = &quot;lungo&quot; }"] -->|"Серіалізація"| B["JSON рядок<br/>{&quot;id&quot;:42,&quot;recipe&quot;:&quot;lungo&quot;}"]
    B -->|"HTTP передача"| C["Мережа"]
    C -->|"Десеріалізація"| D["Kotlin об'єкт<br/>Order(id=42, recipe=&quot;lungo&quot;)"]

    style A fill:#3b82f6,stroke:#1d4ed8,color:#ffffff
    style B fill:#f59e0b,stroke:#b45309,color:#ffffff
    style C fill:#64748b,stroke:#334155,color:#ffffff
    style D fill:#3b82f6,stroke:#1d4ed8,color:#ffffff

Питання — у якому форматі серіалізувати? Від цього вибору залежить швидкість, зручність розробки та сумісність систем.

2. JSON — формат за замовчуванням

JSON (JavaScript Object Notation) — це текстовий формат серіалізації даних, який став стандартом де-факто для HTTP API. Попри назву, JSON давно не прив'язаний до JavaScript і використовується у всіх мовах програмування.

Синтаксис JSON

JSON підтримує шість типів даних:

{
  "id": 42,
  "recipe": "lungo",
  "is_ready": false,
  "volume_ml": 300,
  "price": 10.23,
  "ingredients": ["water", "coffee"],
  "machine": {
    "id": "cm-001",
    "location": "Київ, вул. Хрещатик, 1"
  },
  "completed_at": null
}

{
  "price_wrong": 10.23,
  "price_correct": "10.23",
  "price_as_cents": 1023
}

Серіалізація JSON у Minimal API

ASP.NET Core Minimal API має вбудовану серіалізацію JSON за допомогою System.Text.Json:

var app = WebApplication.Create(args);

app.MapGet("/v1/orders/{id}", (int id) =>
{
    // ASP.NET Core автоматично серіалізує
    // анонімний об'єкт у JSON
    return Results.Ok(new
    {
        id,
        recipe = "lungo",
        volume_ml = 300,
        price = "10.23",   // рядок для точності!
        currency = "UAH",
        is_ready = false
    });
});

app.Run();

Відповідь сервера:

HTTP/1.1 200 OK
Content-Type: application/json

{"id":1,"recipe":"lungo","volume_ml":300,"price":"10.23","currency":"UAH","is_ready":false}

Переваги JSON

Чому саме JSON став стандартом для HTTP API, а не, скажем, XML чи бінарний формат?

3. XML — на випадок, якщо зустрінете

XML (eXtensible Markup Language) — це формат, який домінував у API до ери JSON. Сьогодні XML у нових API зустрічається рідко, але ви точно стикнетесь з ним у SOAP-сервісах, корпоративних інтеграціях та конфігураційних файлах.

<?xml version="1.0" encoding="UTF-8"?>
<order>
  <id>42</id>
  <recipe>lungo</recipe>
  <isReady>false</isReady>
  <volumeMl>300</volumeMl>
  <price currency="UAH">10.23</price>
  <ingredients>
    <ingredient>water</ingredient>
    <ingredient>coffee</ingredient>
  </ingredients>
  <machine>
    <id>cm-001</id>
    <location>Київ, вул. Хрещатик, 1</location>
  </machine>
</order>

JSON vs XML: Порівняння

4. TOML — конфігурації та метадані

TOML (Tom's Obvious Minimal Language) — це формат, спроєктований спеціально для конфігураційних файлів. Він не використовується для передачі даних між клієнтом і сервером у HTTP API, але часто зустрічається в конфігурації сервісів, CI/CD та інструментів розробки.

# Це конфігурація API-сервера
[server]
host = "0.0.0.0"
port = 5000
environment = "production"

[database]
connection_string = "Host=localhost;Database=coffee"
max_pool_size = 20
enable_logging = false

[rate_limiting]
requests_per_minute = 100
burst_size = 20

# Масив таблиць — список ендпоінтів
[[endpoints]]
path = "/v1/orders"
methods = ["GET", "POST"]
auth_required = true

[[endpoints]]
path = "/v1/recipes"
methods = ["GET"]
auth_required = false

Чому TOML, а не JSON?

5. Бінарні формати: Protobuf, FlatBuffers, Avro

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

Protocol Buffers (Protobuf)

Protocol Buffers — це бінарний формат від Google, який є основою gRPC. Дані описуються через .proto-файл (схему), після чого генерується код для серіалізації/десеріалізації.

syntax = "proto3";

message Order {
  int32 id = 1;
  string recipe = 2;
  int32 volume_ml = 3;
  string price = 4;
  string currency = 5;
  bool is_ready = 6;
}

Цей файл компілюється у C#-класи, які автоматично серіалізують/десеріалізують дані у компактний бінарний формат.

Порівняння форматів

6. Стиснення JSON: gzip, brotli, deflate

Частий аргумент проти JSON — його надлишковість: імена полів повторюються для кожного об'єкта в масиві, багато технічних символів (лапки, дужки, коми). Але цей аргумент має важливе застереження: він справедливий лише якщо ми не використовуємо стиснення.

Як працює стиснення в HTTP

Протокол HTTP має вбудовану підтримку стиснення через заголовки Accept-Encoding та Content-Encoding:

sequenceDiagram
    participant C as 📱 Клієнт
    participant S as 🖥️ Сервер

    C->>S: GET /v1/orders<br/>Accept-Encoding: gzip, br
    Note over S: Сервер стискає відповідь<br/>обраним алгоритмом
    S-->>C: 200 OK<br/>Content-Encoding: br<br/>(стиснені дані)
    Note over C: Клієнт розпаковує<br/>автоматично

Алгоритми стиснення

var builder = WebApplication.CreateBuilder(args);

// Додаємо middleware стиснення відповідей
builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
});

var app = builder.Build();
app.UseResponseCompression();

app.MapGet("/v1/orders", () =>
{
    // Відповідь буде автоматично стиснута,
    // якщо клієнт надіслав Accept-Encoding: gzip
    return Results.Ok(new[] 
    {
        new { id = 1, recipe = "lungo" },
        new { id = 2, recipe = "americano" },
        // ... тисячі замовлень
    });
});

app.Run();

using System.IO.Compression;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddResponseCompression(options =>
{
    options.EnableForHttps = true;
    // Надаємо пріоритет Brotli над gzip
    options.Providers.Add<BrotliCompressionProvider>();
    options.Providers.Add<GzipCompressionProvider>();
});

builder.Services.Configure<BrotliCompressionProviderOptions>(
    options => options.Level = CompressionLevel.Optimal
);

var app = builder.Build();
app.UseResponseCompression();

app.MapGet("/v1/orders", () =>
    Results.Ok(new[] 
    {
        new { id = 1, recipe = "lungo" },
        new { id = 2, recipe = "americano" }
    })
);

app.Run();

Ефективність стиснення: числа

Дослідження показують, що gzip практично нівелює різницю у розмірі між JSON та бінарними форматами (Protobuf):

Високопродуктивний парсинг: simdjson

Ще один аргумент проти JSON — «повільна десеріалізація». Стандартні парсери дійсно програють бінарним форматам. Але існують оптимізовані парсери, такі як simdjson, які використовують SIMD-інструкції процесора для паралельного аналізу JSON.

simdjson здатний парсити гігабайти JSON за секунду — продуктивність, якої не вистачить лише екзотичним високочастотним системам.

7. Content Negotiation: як клієнт і сервер домовляються

HTTP має вбудований механізм для узгодження формату даних — Content Negotiation. Клієнт повідомляє серверу, які формати він розуміє, через заголовок Accept:

GET /v1/orders/42 HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, br

Сервер відповідає у запрошеному форматі та вказує його у Content-Type:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Encoding: br

{"id": 42, "recipe": "lungo"}

У Minimal API це працює автоматично для JSON. Якщо вам потрібно підтримати кілька форматів:

var builder = WebApplication.CreateBuilder(args);

// Додаємо підтримку XML-серіалізації
builder.Services.AddEndpointsApiExplorer();

var app = builder.Build();

app.MapGet("/v1/orders/{id}", (int id, HttpContext ctx) =>
{
    var order = new OrderResponse(id, "lungo", 300);

    // Перевіряємо, що хоче клієнт
    var accept = ctx.Request.Headers.Accept
        .FirstOrDefault() ?? "";

    if (accept.Contains("application/xml"))
    {
        // Повертаємо XML
        return Results.Content(
            $"<order><id>{id}</id></order>",
            "application/xml"
        );
    }

    // За замовчуванням — JSON
    return Results.Ok(order);
});

app.Run();

record OrderResponse(int Id, string Recipe, int VolumeMl);

8. Практичні завдання

Рівень 1: Базовий

{
  'name': "Лунго",
  "price": 10.23,
  "ingredients": ["water", "coffee",],
  "machine_id": 001,
  "is_available": True,
  "description": "Довгий еспресо
    з великим об'ємом води"
}

Рівень 2: Порівняльний

Рівень 3: Проєктування

9. Резюме

Далі: у наступній статті ми заглибимось у парадигми клієнт-серверних API — від RPC першого покоління до REST та сучасних технологій (gRPC, GraphQL). Розберемо, чому термін «REST API» неточний і що насправді означає «HTTP API».