Принципы 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?". До встречи!