Розробка REST API для веб-застосунку

Розробка REST API для веб-додатку

REST (Representational State Transfer)—архітектурний стиль API на основі HTTP. Стандарт де-факто для веб-додатків, заснований на ресурсах, HTTP-методах і статус-кодах. Добре спроектований REST API передбачуваний, кешируєтьсяе і масштабується горизонтально.

Ключові принципи

Ресурсоорієнтованість: URL ідентифікує ресурс, HTTP-метод визначає дію:

GET    /api/v1/articles          — список статей
POST   /api/v1/articles          — створити статтю
GET    /api/v1/articles/42       — стаття з id=42
PUT    /api/v1/articles/42       — повне оновлення
PATCH  /api/v1/articles/42       — часткове оновлення
DELETE /api/v1/articles/42       — видалити
GET    /api/v1/articles/42/comments — коментарі статті

Stateless: кожний запит містить всю інформацію, потрібну для його обробки. Без стану сесії на сервері між запитами.

Однорідні відповіді:

// Успіх
{
  "data": { "id": 42, "title": "..." },
  "meta": { "total": 1 }
}

// Список
{
  "data": [...],
  "meta": { "total": 150, "page": 1, "per_page": 20 }
}

// Помилка
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Поле title обов'язкове",
    "details": [{ "field": "title", "message": "required" }]
  }
}

HTTP-коди статусу

Правильне використання кодів—важлива частина контракту:

Пагінація

Три підходи:

Offset-based (page + per_page):

GET /api/articles?page=2&per_page=20

Просто, але повільніше на великих обсягах через OFFSET N в SQL.

Cursor-based (after + limit):

GET /api/articles?after=eyJpZCI6NDJ9&limit=20

Cursor—зашифроване значення останнього запису. Швидко на будь-якому обсязі, але не можна «стрибнути» на сторінку N.

Keyset (after_id + limit): спрощений cursor через перший ID:

GET /api/articles?after_id=42&limit=20

Фільтрація та сортування

GET /api/articles?status=published&author_id=5&created_after=2024-01-01
GET /api/articles?sort=created_at&order=desc&fields=id,title,slug

Включення пов'язаних даних (include):

GET /api/articles/42?include=author,tags,comments_count

Версіонування

URL-версіонування—найбільш явний спосіб:

/api/v1/articles
/api/v2/articles  — breaking change

Альтернатива—Accept header: Accept: application/vnd.app.v2+json.

Приклад реалізації (Laravel)

// routes/api.php
Route::prefix('v1')->middleware('auth:sanctum')->group(function () {
    Route::apiResource('articles', ArticleController::class);
    Route::get('articles/{article}/comments', [CommentController::class, 'index']);
});

// ArticleController
public function index(IndexArticleRequest $request)
{
    $articles = Article::query()
        ->when($request->status, fn($q, $v) => $q->where('status', $v))
        ->with($request->include ?? [])
        ->paginate($request->per_page ?? 20);

    return ArticleResource::collection($articles);
}

Терміни

REST API для CRUD-додатку (10–20 ендпоїнтів, аутентифікація, валідація, документація): 1–2 тижні.