How to Design a REST API (переклад статті https://restfulapi.net/rest-api-design-tutorial-with-example/)

rest.md

Проєктування REST API — основні положення

Переклад ключових тез статті з restfulapi.net

---

Що таке REST API

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

---

6 архітектурних обмежень REST

Обмеження	Суть
Єдиний інтерфейс	Кожен ресурс має єдиний URI; взаємодія — через стандартні HTTP-методи
Клієнт–сервер	Клієнт і сервер розвиваються незалежно
Без збереження стану	Кожен запит містить всю необхідну інформацію; сесії на сервері — відсутні
Кешування	Відповіді мають позначатись як кешовані або ні
Багаторівневість	Клієнт не знає, з яким саме вузлом він спілкується
Код на вимогу (опційно)	Сервер може повертати виконуваний код (наприклад, JS-віджет)

Порада: порушення одного-двох обмежень не робить API «не-REST» — але чим більше дотримано, тим краще масштабованість і супроводжуваність.

---

Крок 1 — Моделювання об'єктів

Перший крок — визначити ресурси системи. Для мережевого застосунку це можуть бути пристрої та їхні конфігурації:

• Device — пристрій із полями id, description, status тощо
• Configuration — налаштування пристрою (підресурс Device)

Кожен об'єкт повинен мати унікальний ідентифікатор (id).

---

Крок 2 — Проєктування URI

Правила побудови URI:

• Тільки іменники — дієсловам у URI не місце
• Ієрархія відображає зв'язок «ресурс → підресурс»
• Колекції — у множині

GET  /devices                          # список пристроїв
GET  /devices/{id}                     # один пристрій
GET  /devices/{id}/configurations      # конфігурації пристрою
GET  /devices/{id}/configurations/{configId}

❌ /getDevice, /createConfiguration — так не можна
✅ /devices, /devices/{id}/configurations — правильно

---

Крок 3 — HTTP-методи та їхня семантика

Метод	Дія	Ідемпотентний?
GET	Отримати ресурс	✅
POST	Створити ресурс	❌
PUT	Повністю замінити ресурс	✅
PATCH	Частково оновити ресурс	✅
DELETE	Видалити ресурс	✅

Ідемпотентність важлива для надійності: якщо мережа дала збій і клієнт повторив PUT або DELETE — побічних ефектів не виникне. З POST — інакше, повторний виклик може створити дублікат.

---

Крок 4 — Формат представлень

• Найпоширеніший формат — JSON (або XML)
• Колекції повертають короткий опис ресурсів; детальна інформація — по окремому URI
• Для великих колекцій застосовують пагінацію:

GET /devices?startIndex=0&size=20
GET /configurations?startIndex=0&size=20

---

Крок 5 — HTTP-коди відповідей

Правильні статус-коди — частина контракту API:

Код	Значення
200 OK	Успіх (GET, PUT)
201 Created	Ресурс створено (POST)
204 No Content	Успіх без тіла (DELETE)
400 Bad Request	Помилка клієнта
404 Not Found	Ресурс не знайдено
500 Internal Server Error	Помилка сервера

❌ Повертати 200 OK у разі помилки — поширена і груба помилка.

---

Додаткові аспекти дизайну

HATEOAS

Ресурс може містити посилання (links) на пов'язані ресурси — клієнту не потрібно знати URI наперед, він їх «відкриває» динамічно. На практиці повний HATEOAS рідко реалізують, але додавання _links у відповідь підвищує зручність API.

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

Закладайте версію з першого дня:

/api/v1/devices
/api/v2/devices

Безпека та автентифікація

• Використовуйте Bearer-токени (JWT) у заголовку Authorization
• Не зберігайте стан сесії на сервері — це руйнує горизонтальне масштабування

Консистентність

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

---

Підсумок

Ресурси → URI (іменники) → HTTP-методи → Формат → Коди відповідей

Дотримання цих принципів дає API, який легко споживати, тестувати, масштабувати і розвивати незалежно від клієнтів.