Хороший API — як хороша розмова
REST API — це контракт між вашим бекендом та клієнтами. Якщо контракт незрозумілий — інтеграція стає кошмаром.
Ресурси, не дії
URL має описувати ресурс, а не дію. Використовуйте іменники, не дієслова. HTTP-метод вже описує дію.
Пагінація: завжди та з метаданими
Ніколи не повертайте всі записи. Повертайте пагіновані результати з метаданими: current_page, per_page, total, last_page.
Консистентні відповіді помилок
Кожна помилка має повертатися в одному форматі з правильними HTTP статус-кодами: 400, 422, 401/403, 500.
Версіонування API
V1 продовжує працювати, v2 вводить breaking changes. Так ви не ламаєте існуючі клієнти.
Фільтрація та rate limiting
API має підтримувати гнучкі запити через query parameters та інформувати клієнтів про ліміти через заголовки.
Висновок
Хороший API дизайнитьтся з огляду на споживача. Консистентність, передбачуваність та зворотна сумісність — це інвестиції.