Проектирование API: пагинация, идемпотентность, версионирование, обратная совместимость?

#Принципы хорошего API

Соглашения, которые стоит зафиксировать в гайдлайне команды: camelCase в JSON, даты в ISO 8601 UTC (2025-09-30T10:15:00Z), деньги — строкой или минимальными единицами с валютой, идентификаторы — строками (не раскрывать последовательные int), перечисления — строками.

#Пагинация

public record Page<T>(IReadOnlyList<T> Items, string? NextCursor);

public async Task<Page<OrderDto>> ListAsync(string? after, int limit, CancellationToken ct)
{
    var q = db.Orders.AsNoTracking().OrderByDescending(o => o.CreatedAt).ThenByDescending(o => o.Id).AsQueryable();
    if (Cursor.TryDecode(after, out var c))
        q = q.Where(o => o.CreatedAt < c.CreatedAt || (o.CreatedAt == c.CreatedAt && o.Id.CompareTo(c.Id) < 0));

    var items = await q.Take(limit + 1).Select(o => new OrderDto(o.Id, o.Total, o.CreatedAt)).ToListAsync(ct);
    var next = items.Count > limit ? Cursor.Encode(items[limit - 1].CreatedAt, items[limit - 1].Id) : null;
    return new Page<OrderDto>(items.Take(limit).ToList(), next);   // курсор — непрозрачная base64-строка
}

#Идемпотентность

Детали реализации:

• Ключ генерирует клиент (UUID) на одну логическую операцию и повторяет его при ретраях.
• Сервер хранит ключ + хэш тела запроса + ответ (TTL, например, 24 ч). Тот же ключ с другим телом — 422.
• Параллельный повтор, пока первый ещё обрабатывается, — 409 (или ожидание).
• Запись ключа и бизнес-изменение — в одной транзакции, иначе сбой между ними сломает гарантию.

#Эволюция контракта

Стратегия expand → migrate → contract: добавить новое поле рядом со старым, перевести клиентов, затем удалить старое (в новой версии или после срока депрекации).

#Версионирование

builder.Services.AddApiVersioning(o =>
{
    o.DefaultApiVersion = new ApiVersion(1);
    o.ReportApiVersions = true;                     // заголовок api-supported-versions
    o.ApiVersionReader = new UrlSegmentApiVersionReader();
});

var api = app.NewVersionedApi("Orders");
var v1 = api.MapGroup("/api/v{version:apiVersion}/orders").HasApiVersion(1).HasDeprecatedApiVersion(1);
var v2 = api.MapGroup("/api/v{version:apiVersion}/orders").HasApiVersion(2);
v1.MapGet("/{id}", GetOrderV1);
v2.MapGet("/{id}", GetOrderV2);

Депрекация: заголовки Deprecation и Sunset: Sat, 31 Jan 2026 00:00:00 GMT, ссылки на гайд миграции, метрики использования старой версии по клиентам, уведомления партнёрам.

#Конкурентные изменения: ETag

GET /api/orders/42           → 200, ETag: "v17"
PUT /api/orders/42           If-Match: "v17"    → 200, ETag: "v18"
PUT /api/orders/42           If-Match: "v17"    → 412 Precondition Failed (кто-то уже изменил)

ETag удобно строить из версии строки (xmin/rowversion) — это HTTP-обёртка над оптимистичной конкуренцией EF Core.

#REST, gRPC или GraphQL

#Вопросы на засыпку

#Итог

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