Процес проєктування API та документування

1. Чому процес важливий

Книга Константинова наголошує: API — це контракт. На відміну від внутрішнього коду, який можна рефакторити коли завгодно, API не можна змінити після публікації без наслідків. Кожен клієнт, що інтегрувався з вашим API, залежить від його поточної поведінки.

Наслідки поганого проєктування:

Вартість виправлення зростає експоненційно з кожним кроком:

graph LR
    A["🧠 Проєктування<br/>$1"] --> B["💻 Реалізація<br/>$10"]
    B --> C["🧪 Тестування<br/>$100"]
    C --> D["📦 Продакшн<br/>$1000"]
    D --> E["🌍 Зовнішні клієнти<br/>$10 000"]

Виправити помилку на етапі проєктування — дешево. Виправити ту саму помилку, коли 1000 клієнтів вже інтегрувалися — дуже дорого.

2. Покроковий алгоритм проєктування

/v1/recipes                    — рецепти (колекція)
/v1/recipes/{id}               — конкретний рецепт
/v1/coffee-machines             — кавові машини
/v1/coffee-machines/{id}       — конкретна машина
/v1/orders                     — замовлення
/v1/orders/{id}                — конкретне замовлення
/v1/orders/{id}/attachments    — вкладення замовлення

3. OpenAPI / Swagger

Що таке OpenAPI

OpenAPI (раніше Swagger) — це стандарт для опису HTTP API. Він дозволяє визначити всі ендпоінти, параметри, формати запитів/відповідей та помилки у машиночитаємому форматі (YAML або JSON).

Навіщо це потрібно:

• Автогенерація документації — Swagger UI створює інтерактивну документацію
• Автогенерація клієнтів — бібліотеки для будь-якої мови програмування
• Валідація — перевірка запитів і відповідей на відповідність специфікації
• Тестування — інструменти можуть генерувати тести з документації
• Контракт — розробники клієнта і сервера працюють від одного документа

OpenAPI у ASP.NET Core

ASP.NET Core Minimal API автоматично генерує OpenAPI-специфікацію:

var builder = WebApplication.CreateBuilder(args);

// Додаємо OpenAPI
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new()
    {
        Title = "Coffee API",
        Version = "v1",
        Description = "API для замовлення кави"
    });
});

var app = builder.Build();

// Включаємо Swagger UI (тільки для розробки!)
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Збагачення документації

Minimal API автоматично визначає базову інформацію з коду, але для якісної документації потрібні додаткові метадані:

app.MapGet("/v1/orders/{id}", (Guid id) =>
{
    var order = db.GetOrder(id);
    return order is not null
        ? Results.Ok(order)
        : Results.NotFound();
})
.WithName("GetOrderById")
.WithSummary("Отримати замовлення за ID")
.WithDescription(
    "Повертає повну інформацію про замовлення. " +
    "UUID формат для ідентифікатора.")
.Produces<Order>(200)
.Produces<ApiError>(404)
.Produces<ApiError>(401)
.WithTags("Orders");

4. Версіонування та зворотна сумісність

Що є зломом зворотної сумісності

Не всі зміни ламають клієнтів. Розрізнення breaking та non-breaking змін критичне:

Коли створювати нову версію

Нова версія API (/v2/...) потрібна тільки коли:

1. Breaking changes неминучі (переробка моделі даних)
2. Стара версія підтримується паралельно (мінімум 6-12 місяців)
3. Міграційний план задокументований (як клієнту перейти з v1 на v2)

Нова версія — це фактично новий API, який потрібно підтримувати разом зі старим. Це дорого.

5. Code style та конвенції

Єдині правила для всієї команди

Книга Константинова наголошує: консистентність важливіша за будь-яке конкретне правило. Краще мати «неідеальні» правила, яких дотримуються всі, ніж ідеальні, яких не дотримується ніхто.

Чеклист конвенцій

Визначте та задокументуйте наступне:

URL:

• Множина для колекцій (/orders, не /order)
• Тільки lowercase та дефіси (coffee-machines, не CoffeeMachines)
• Версія в path (/v1/...)
• Без слешу наприкінці (/orders, не /orders/)

JSON:

• Один стиль для імен: snake_case або camelCase (обрати один!)
• Дати у ISO 8601 ("2024-02-26T14:30:00Z")
• Гроші як рядки або у мінімальних одиницях
• Enum-и як рядки ("active", не 1)
• Null-поля: повертати як null чи не повертати?

Помилки:

• Єдиний формат ApiError для всіх помилок
• reason — унікальний для кожного типу помилки
• localized_message — для кінцевого користувача
• developer_message — для розробника
• 5xx — без деталей назовні

Пагінація:

• Курсорна (не offset)
• Ліміт за замовчуванням та максимальний
• Формат відповіді: items, next_cursor, has_more

Безпека:

• HTTPS обов'язково
• UUID для зовнішніх ідентифікаторів
• JWT з коротким часом життя
• Rate limiting для всіх ендпоінтів

6. Документація як продукт

Що повинна містити документація

Хороша документація API — це не просто список ендпоінтів. Вона повинна включати:

Помилки документації

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

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

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

8. Резюме модуля

Ми пройшли весь шлях від базових концепцій до повного алгоритму проєктування: