Главная Мануалы REST API с нуля — курс для новичка GET, POST, PUT, PATCH, DELETE — CRUD на пальцах

GET, POST, PUT, PATCH, DELETE — CRUD на пальцах

HTTP-методов на самом деле девять. Но в повседневной REST-работе используются пять: GET, POST, PUT, PATCH, DELETE. Остальные (HEAD, OPTIONS, CONNECT, TRACE) либо выполняются браузером автоматически, либо встречаются в очень специальных контекстах. Их разберём в конце главы коротко.

CRUD: четыре буквы, четыре операции

Если у нас есть какой-то ресурс — пост, пользователь, заказ — над ним обычно нужно делать четыре действия:

Create — создать новый;
Read — прочитать существующий;
Update — обновить;
Delete — удалить.

Аббревиатура CRUD пришла из мира баз данных, но в REST она прижилась: каждой букве соответствует свой HTTP-метод. Вот таблица соответствий, к которой будем возвращаться весь курс:

CRUD	HTTP-метод	Типичный URL	Что делает
Read (один)	GET	/posts/42	Вернуть пост 42
Read (список)	GET	/posts	Вернуть все посты (часто с фильтрами и пагинацией)
Create	POST	/posts	Создать новый пост; id присвоит сервер
Update (целиком)	PUT	/posts/42	Перезаписать пост 42 целиком
Update (частично)	PATCH	/posts/42	Изменить отдельные поля поста 42
Delete	DELETE	/posts/42	Удалить пост 42

GET: достать данные

Самый частый метод. Браузер делает GET, когда вы открываете страницу, переходите по ссылке, загружаете картинку или скрипт. В REST API он отвечает за чтение.

GET /api/posts          ← все посты
GET /api/posts/42       ← один пост
GET /api/posts?author=anna&limit=5  ← с фильтром

У GET не должно быть тела — всё, что нужно сказать серверу, выражается через путь и query-параметры. Сервер должен вернуть данные ресурса. Если ресурса не существует — ответ 404.

POST: создать новое

Когда нужно создать ресурс, у которого ещё нет id, шлём POST в коллекцию:

POST /api/posts
Content-Type: application/json

{"title": "Новый пост", "body": "Текст..."}

Сервер присваивает id, сохраняет запись и обычно отвечает кодом 201 (Created), возвращая в теле созданный ресурс с присвоенным id. Часто также добавляет заголовок Location с адресом нового ресурса.

Кроме создания, POST используется как «универсальное действие, которое не помещается в другие методы» — например, «отправить форму», «запустить рассылку», «конвертировать файл». Это неидеологичное использование — но в реальной жизни нормальное.

PUT: перезаписать целиком

Когда нужно обновить ресурс полностью — шлём PUT на конкретный URL ресурса:

PUT /api/posts/42
Content-Type: application/json

{"title": "Новый заголовок", "body": "Новое тело", "author": "anna"}

Важная особенность PUT — тело должно содержать весь ресурс. Если в исходном посте было пять полей, а вы послали три, остальные два должны либо обнулиться, либо принять дефолт. Это и есть «перезапись целиком».

PATCH: обновить выборочно

Когда нужно изменить только одно поле, не трогая остальные:

PATCH /api/posts/42
Content-Type: application/json

{"title": "Только новый заголовок"}

Сервер обновит только переданные поля. Это удобнее и эффективнее, чем PUT, когда меняется одно поле из двадцати.

В реальной жизни много API не реализует PATCH и использует PUT для частичных обновлений тоже — это технически некорректно, но встречается. Когда выбираете между PUT и PATCH — смотрите документацию конкретного API.

DELETE: удалить

DELETE /api/posts/42

Тело у DELETE обычно не отправляют. Ответ — либо 204 (No Content), если удалили молча, либо 200 с телом, в котором сервер возвращает то, что удалил (для отмены, журналирования).

Кратко об остальных методах

HEAD — то же, что GET, но сервер возвращает только заголовки без тела. Используется для проверки существования ресурса или его метаданных (размер, дата модификации) без скачивания.
OPTIONS — запрос «а что вообще можно с этим URL». Сервер отвечает заголовком Allow: GET, POST, PUT. Главное практическое применение для фронта — preflight-запросы CORS. Об этом в модуле 8.
CONNECT и TRACE — служебные методы, в REST-разработке руками не используются.

Правило выбора

Когда заходите в новый REST API, держите в голове простой алгоритм:

Читаете — GET.
Создаёте новый ресурс — POST в коллекцию.
Меняете весь ресурс целиком — PUT.
Меняете отдельное поле — PATCH.
Удаляете — DELETE.

Если документация требует иначе — делайте, как требует документация. Иногда сервис не следует REST-конвенциям, и спорить с этим бесполезно. Главное — знать, как правильно по канонам, чтобы видеть отклонения.

Предыдущая Следующая