REST API: представление действий с помощью протокола HTTP

Протокол HTTP является основой для проектирования REST API, предоставляя стандартные методы: GET, POST, PUT, PATCH, DELETE для взаимодействия с ресурсами.

Эти методы соответствуют базовым операциям CRUD: Create, Read, Update, Delete, но также могут использоваться для реализации более сложных сценариев. Рассмотрим, как систематизировать действия с ресурсами, используя, как пример каталог товаров.

➡️ POST: Добавление товара
HTTP-представление цели «Добавить товар в каталог» — POST /products. Когда мы добавляем товар в ресурс каталога, обозначенный как /products, мы фактически создаем ресурс товара, используя предоставленную информацию о товаре.
🔚HTTP-метод, соответствующий созданию ресурса — это POST.
🔚Параметры метода запроса POST обычно передаются в теле запроса, поэтому параметр информации о товаре отправляется туда.
🔚Как только ресурс товара создан, действие должно вернуть вновь созданный ресурс, идентифицируемый по его пути: /products/{AddedProductId}.

http
POST /products HTTP/1.1
Content-Type: application/json
{
"name": "Ноутбук",
"price": 999.99,
"description": "Мощный игровой ноутбук"
}

➡️ GET с параметрами запроса: Поиск товаров
HTTP-представление поиска товаров в каталоге с использованием запроса – GET /products?free-query={query}.
🔚Когда мы ищем товары, мы хотим получить их, поэтому должны использовать HTTP-метод GET в пути /products. Чтобы получить только те товары, которые соответствуют некоему запросу, например названию товара или частичному описанию, нужно передать параметр в этот запрос.
🔚Параметры HTTP-запроса GET обычно предоставляются в виде параметров запроса в пути:

— GET /example?param1=value1&param2=value2
— GET /products?free-query=something

🔚Параметры расположены после знака ? в конце пути и предоставляются в формате имя = значение (например, param1=value1). Несколько параметров запроса разделяются символом &.
🔚Как только поиск будет завершен, метод запроса GET возвращает список товаров, соответствующих критерию.

http
GET /products?free-query=ноутбук HTTP/1.1

➡️ GET с идентификатором: Получение конкретного товара
Мы хотим получить ресурс товара, обозначенный как /products/ {productId}, поэтому снова используем HTTP-метод GET.
🔚HTTP-представление – это GET/products/{productId}.
🔚Метод GET извлекает ресурс по его уникальному идентификатору.
🔚Идентификатор указывается в пути запроса.

http
GET /products/123 HTTP/1.1

➡️ DELETE: Удаление товара
🔚HTTP-представление: DELETE /products/{productId}
🔚Метод DELETE удаляет ресурс по указанному пути.
🔚Ответ сервера обычно не содержит данных.

http
DELETE /products/123 HTTP/1.1

➡️ PATCH: Частичное обновление
🔚HTTP-представление обновления товара – это PATCH /products/{productId}
🔚Метод PATCH обновляет только указанные поля ресурса.
🔚Данные для обновления передаются в теле запроса.
Например, если вы хотите обновить цену товара – можно использовать метод PATCH для ресурса товара и передать обновленную цену в теле.

http
PATCH /products/123 HTTP/1.1
Content-Type: application/json
{
"price": 899.99
}

➡️ PUT: Полная замена
🔚HTTP-представление: PUT /products/{productId}
🔚Метод PUT полностью заменяет ресурс. Если ресурса нет, он может быть создан.
🔚Тело запроса содержит все поля ресурса.

http
PUT /products/123 HTTP/1.1
Content-Type: application/json
{
"name": "Ноутбук Pro",
"price": 1299.99,
"description": "Профессиональная модель"
}

🔣 За пределами CRUD: рекомендации по выбору методов
➡️ Если действие не вписывается в стандартные CRUD-операции, используйте:
🔚POST для действий, которые не являются идемпотентными, например: отправка формы, запуск процесса.
🔚GET для безопасных операций без изменения состояния, например: фильтрация, сортировка.

➡️ Примеры расширенных действий:
🔚POST — Создание клиента, загрузка файла.
🔚GET — Поиск ресторанов, фильтрация товаров.
🔚PUT/PATCH — Изменение статуса заказа, обновление лимита карты.
🔚DELETE — Отмена заказа, удаление учетной записи.

#аналитик #навыкАналитика #API #REST #IT