Ответ
REST API опирается на стандартные HTTP-методы (глаголы) для выполнения операций CRUD (Create, Read, Update, Delete) с ресурсами. Каждый метод идемпотентен и безопасен в определенной степени.
Основные HTTP-методы в REST:
| Метод | Идемпотентность | Безопасность | Операция | Пример (ресурс /books) |
|---|---|---|---|---|
| GET | Да | Да | Получение данных (одного или списка ресурсов). Не должен изменять состояние сервера. | GET /books — получить список книг.GET /books/42 — получить книгу с id=42. |
| POST | Нет | Нет | Создание нового ресурса. Тело запроса содержит данные для создания. | POST /books — создать новую книгу. |
| PUT | Да | Нет | Полное обновление ресурса. Тело запроса содержит новое представление ресурса, заменяющее старое. Если ресурс не существует, может создавать его (зависит от реализации). | PUT /books/42 — полностью заменить данные книги с id=42. |
| PATCH | Нет* | Нет | Частичное обновление ресурса. Тело запроса содержит только изменяемые поля. | PATCH /books/42 — обновить только цену книги с id=42. |
| DELETE | Да | Нет | Удаление указанного ресурса. | DELETE /books/42 — удалить книгу с id=42. |
*PATCH не является строго идемпотентным по спецификации, но должен быть таковым при правильной реализации.
Пример запроса POST для создания книги:
POST /api/books HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>
{
"title": "Clean Code",
"author": "Robert C. Martin",
"year": 2008
}Ожидаемый успешный ответ:
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/books/101
{
"id": 101,
"title": "Clean Code",
"author": "Robert C. Martin",
"year": 2008
}Ответ 18+ 🔞
А, ну вот, опять про эти ваши REST API, блядь. Сидят, умничают, глаголы HTTP разбирают, как будто в церкви на службе. Давайте я вам на пальцах, сука, объясню, как это всё работает, а то вы тут с идемпотентностью своей заебали всех.
Смотрите сюда, вся суть в том, что у вас есть какой-то ресурс, ну, например, /books — это ваши книжки. И чтобы с ними что-то сделать, вы не просто так в темную тыкаете, а используете специальные команды, которые называются HTTP-методы. Их, блядь, всего несколько, но они охватывают всю вашу жалкую CRUD-жизнь.
Вот эти ваши священные глаголы, разжёванные:
| Метод | Идемпотент? | Безопасен? | Что делает? | Пример (с книжками /books) |
|---|---|---|---|---|
| GET | Да | Ага, как же | Читает данные. Ничего не портит, не меняет. Просто смотрит. | GET /books — посмотреть список всех книг.GET /books/42 — посмотреть конкретно на книгу номер 42. |
| POST | Нихуя! | Нет | Создает новый ресурс. Ты ему в тело запроса суёшь данные, а он рожает новую сущность. | POST /books — родить новую книжку на свет. |
| PUT | Да, ёпта! | Нет | Полностью переписывает ресурс. Старые данные — нахуй, новые — на трон. Если ресурса нет — может и создать, хитрая жопа. | PUT /books/42 — взять книгу номер 42 и переписать её заново от корки до корки. |
| PATCH | Ну, в теории да* | Нет | Подправляет ресурс. Не весь, а только кусочек. Типа, "ой, тут цена не та, давайте исправим". | PATCH /books/42 — поменять только цену у книги номер 42, а всё остальное оставить как было. |
| DELETE | Абсолютно! | Нет | Удаляет ресурс. Нахуй, в топку, безвозвратно. | DELETE /books/42 — отправить книгу номер 42 в небытие. |
*С PATCH'ем, конечно, история. По идее, он должен быть идемпотентным, но если криворукие разрабы накосячат — то и не будет. Ёперный театр.
Вот смотрите, как это выглядит вживую. Хотите создать книжку? Отправляете POST-запрос:
POST /api/books HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>
{
"title": "Clean Code",
"author": "Robert C. Martin",
"year": 2008
}А сервер, если он не совсем мудак, отвечает вам примерно так:
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/books/101
{
"id": 101,
"title": "Clean Code",
"author": "Robert C. Martin",
"year": 2008
}Вот и вся магия, блядь. Никакой ебалы-переебалы. Сказал серверу, что делать — GET'ом посмотреть, POST'ом создать, PUT'ом переписать, PATCH'ом подлатать или DELETE'ом удалить. Главное — не путать их местами, а то получится пиздец вместо API.