Принципи REST: ресурси, HTTP-методи, код відповіді

Давай почнемо з маніфесту REST API: ресурси — це альфа і омега, суть усього REST. Пам'ятай, ми вже обговорювали, що REST API працює з об'єктами, а не з діями? У REST будь-який об'єкт, з яким взаємодіє твій сервер, називається ресурсом. Твоє завдання — грамотно "адресувати" цей ресурс, щоби клієнт міг його знайти. Тут на сцену виходить URI.

URI (Uniform Resource Identifier) — це унікальна адреса для якогось ресурсу на твоєму сервері. Спрощено: якщо твій сервер — це великий склад, то URI — це адреса стелажа, де лежить потрібна коробка (твій ресурс).

Приклад простого URI:

https://api.example.com/users

Як правильно проектувати URI?

Договоримося відразу: URI — це не щось "на винос". Це як вітрина твого магазину — вона має бути привабливою і давати потенційному покупцю зрозуміти, чим тут торгують.

Ось кілька порад:

1. Використовуй іменники, а не дієслова.
   • Правильно: /users, /products/{productId}/reviews.
   • Неправильно: /getUsers, /deleteProduct.
2. Використовуй множину для груп ресурсів.
   • Наприклад, /users для опису всіх користувачів.
3. Використовуй ієрархію для вкладених ресурсів.
   • Наприклад, якщо хочеш отримати замовлення конкретного користувача: /users/{userId}/orders.
4. URI — це не дієслова і не дії. Ти їх визначаєш через HTTP-методи (про це трохи далі).

Приклад:

GET https://api.example.com/users
POST https://api.example.com/users
GET https://api.example.com/users/123

HTTP-методи: головні герої REST

HTTP-методи — це ключові оператори для роботи з ресурсами в REST API.

REST API суворий у своїй простоті. Якщо хочеш додати нового користувача, використовуй POST. Хочеш його видалити? Використай DELETE. А якщо раптом вирішиш оновити його телефон і додаш запит GET /users/updatePhone?id=123, то карма твого REST API буде безнадійно зіпсована.

Приклад: Управління користувачами через HTTP-методи

GET    /users         - Отримати всіх користувачів
POST   /users         - Створити нового користувача
GET    /users/123     - Отримати конкретного користувача
PUT    /users/123     - Повністю оновити користувача 123
PATCH  /users/123     - Оновити лише частину даних користувача 123
DELETE /users/123     - Видалити користувача 123

Якщо б API був мобільним додатком, HTTP-методи — це кнопки "Додати", "Видалити", "Оновити".

HTTP-коди відповіді: твої друзі в дебагу

Коли сервер отримує запит, він має якось повідомити клієнту результат операції. Саме для цього існують HTTP коди відповіді. Вони поділяються на групи, але без "двійників".

Основні коди, які потрібно знати

2xx: успішні коди

• 200 OK: усе пройшло гладко. Сервер повернув дані.
• 201 Created: твій ресурс було успішно створено.
• 204 No Content: запит оброблено, але повертати нічого.

4xx: помилки клієнта

• 400 Bad Request: щось не так із запитом (наприклад, JSON невалідний).
• 401 Unauthorized: ти не авторизований.
• 403 Forbidden: у тебе немає прав.
• 404 Not Found: ресурс не знайдено.

5xx: помилки сервера

• 500 Internal Server Error: загальний код для серверної проблеми.
• 503 Service Unavailable: "вибач, я пішов на обід. Спробуй пізніше."

Приклад роботи з кодами

Припустимо, у тебе є API для управління книгами:

GET /books/{bookId}

1. Якщо книгу знайдено, сервер поверне 200 OK і дані книги.
2. Якщо книгу не знайдено, отримаєш 404 Not Found.
3. Якщо сервер вирішить "стрельнути собі у ногу", ймовірність отримати 500 Internal Server Error висока.

Підсумовуємо

Сьогодні ми розглянули три основні принципи REST:

1. Ресурси та їх представлення через URI.
2. HTTP-методи, які дозволяють взаємодіяти з ресурсами.
3. Коди відповіді HTTP, які роблять твій API дружелюбним до клієнта.

Тепер ти готовий перейти до створення своїх перших REST-контролерів. І ще: ніколи не називай API "простим", поки сам його не потестив за допомогою штуковин типу Postman. REST API — простий доти, доки в нього не прийде запит від клієнта з параметром foo=bar&baz=<injected_script>.

В наступній лекції почнемо реалізацію REST API контролерів. Готуйся до анотацій, JSON і нескінченних питань "Чому в мене 404?". До зустрічі!