Блок 3 · Урок 3 из 4

REST: ресурсы, методы, статус-коды

Самый распространённый стиль API — набор соглашений, благодаря которым, поняв одно API, вы понимаете почти любое.

⏱ ≈ 8 минут 🧩 соглашения API 🎯 цель: предсказывать устройство API и быстро диагностировать сбои

Зачем это вам

«Сделаем REST API», «это RESTful», «это не очень по REST» — эти фразы встречаются в каждом втором проекте. Понимая REST, вы сразу схватываете архитектурный замысел, не вникая в детали. А связка статус-код + метод + эндпоинт (адрес запроса) даёт мгновенную диагностику: видите GET /products/42 → 404 и без лишних слов понимаете — такого товара нет.

Главная идея

REST — это договорённость, а не технология

REST (Representational State Transfer) — стиль построения API, предложенный Роем Филдингом в 2000 году.1 Не язык, не протокол — набор соглашений о том, как называть адреса и какими методами работать с данными.

Центральная идея REST: данные представлены как ресурсы (resource) — сущности вроде товаров, пользователей, заказов. У каждого ресурса есть свой URL. А действия над ресурсами выражаются стандартными HTTP-методами, которые вы уже знаете из блока 1: GET (читать), POST (создать), PUT/PATCH (изменить), DELETE (удалить). Каждый ответ сопровождается статус-кодом — тоже из блока 1 (200, 201, 404, 500 и другие).

Главная ценность REST — предсказуемость.2 Потому что соглашения одинаковые везде: выучили логику в одном API — понимаете любое другое, построенное по тем же правилам.

Запрос Что делает Типичный статус
GET /products Список товаров 200 OK
GET /products/42 Товар №42 200 OK или 404
POST /products Создать товар 201 Created
PUT /products/42 Заменить товар №42 целиком 200 OK
PATCH /products/42 Изменить часть данных товара №42 200 OK
DELETE /products/42 Удалить товар №42 200 OK или 204 No Content

📌 Зная стиль REST, по методу и адресу угадываете, что делает запрос, ещё до чтения документации. Это и есть главная выгода соглашений.

Аналогия, которую можно пересказать

Единый порядок в сети библиотек

Книги с адресами на полках— ресурсы с URL: /products/42, /users/7
Стандартные действия читателя— HTTP-методы: посмотреть (GET), сдать новую книгу в фонд (POST), заменить экземпляр (PUT/PATCH), списать (DELETE)
Единый порядок во всех филиалах— соглашения REST: разобрались в одном API — ориентируетесь в любом
Ответ библиотекаря— статус-код: «выдано» (200), «создано» (201), «такой книги нет» (404), «у нас авария» (500)

Вывод: общие правила важнее частностей. Поняв стиль, понимаете все API в этом стиле — точно так же, как зная порядок в одном филиале библиотечной сети, вы сразу ориентируетесь в любом другом.

Запомните одно

REST — договорённость об именах и действиях

REST — это не технология, а договорённость об именах и действиях. Её ценность — предсказуемость: одно выученное правило работает для тысяч разных API. Именно поэтому агенты и разработчики по умолчанию строят API в стиле REST — меньше объяснять, меньше удивляться.

Что это даёт на практике

Фраза агента → что он имеет в виду

«Сделаем REST API»
API по стандартным соглашениям: ресурсы по URL + HTTP-методы + статус-коды. Поняв структуру — сразу знаете, как устроены все адреса.
«GET /users/42 вернул 404»
Запрашиваемого пользователя нет по этому адресу. Либо его удалили, либо ID неверный — дальше разбирайте именно это.
«Это не очень RESTful»
API отступает от привычных соглашений — например, использует GET там, где должен POST. Будет менее предсказуемым; придётся читать документацию внимательнее.
«POST создаёт, PUT обновляет»
Разные методы под разные действия над одним ресурсом. POST → новая запись (ответ 201 Created). PUT → замена существующей (ответ 200 OK).

REST — стиль (архитектурный подход) построения API: ресурсы + URL + HTTP-методы + статус-коды.

Ресурс (resource) — сущность, доступная по своему URL: товар, пользователь, заказ.

RESTful — про API, следующее соглашениям REST.

Метод и статус-код — глагол действия (GET, POST, PUT…) и трёхзначный код результата (200, 201, 404, 500…) — из блока 1.

Проверьте себя

Четыре вопроса с мгновенной проверкой

1. Что такое REST?

2. GET /orders/15 по соглашениям REST означает…

3. Зачем REST нужны соглашения?

4. Агент сообщает: «POST вернул 201». Это…

Куда мы идём

Программа курса — 7 блоков