CRUD — HTTP API

В программировании аббревиуатура CRUD обозначет 4 базовых операции над информацией: создание, чтение, обновление и удаление. CRUD строят вокруг какой-то сущности, например пользователя. Для этого создают либо интерфейс формами, либо HTTP API эндпоинты.

Сервис https://dummyjson.com как раз предоставляет такой набор операций для своих сущностей. Рассмотрим их подробнее.

В целях безопасности, этот сервис не выполняет реальных изменений на сервере. Все операции выглядят так как будто они вносят изменения, но изменения, на самом деле, не происходят

1 - это идентификатор конкретного пользователя. Он будет меняться, в зависимости от того, с каким пользователем мы работаем прямо сейчас. Кстати идентификатор не обязательно должен быть числом, здесь все зависит от того, что бекенд считает идентификатором и как он создается в базе данных. Например в MongoDB идентификатор состоит из чисел и букв.

Обратите внимание на использование методов HTTP. У них есть определенный смысл и он здесь используется. GET нужен для извлечения данных, POST для отправки форм (создания), PATCH для обновления и DELETE для удаления. URL, при этом, часто остается одним и тем же.

Использование подходящих методов имеет важное значение в API. Любые HTTP запросы, которые ходят в интернете, обрабатываются веб-серверами и промежуточными прокси, которые могут находиться на пути к веб-серверу. И веб-сервер и прокси знают про особенности HTTP и в зависимости от параметров запроса могут делать различные оптимизации, например, кешировать результат.

Кеширование это техника, которая позволяет веб-серверу или прокси сохранить ответ от сервера и отдавать его при следующих запросах без обращения к самому серверу. Кеширование значительно ускоряет доступ к ресурсам и разгружает сервера. Например GET можно кешировать для ускорения доступа так как GET никогда не меняет данные, то есть это безопасно. Методы POST, PATCH и DELETE кешировать нельзя, они должны приходить на сервер, так как они вносят изменения.

Добавление пользователя

В соответствии с документацией для добавления пользователя мы должны отправить POST запрос на эндпоинт https://dummyjson.com/users/add. Данные могут быть отправлены в разных форматах, например, как данные обычной HTML-формы или как JSON. Для использования JSON, во время подготовки запроса нужно выполнить два шага:

• Указать заголовок Content-Type со значением application/json
• Преобразовать данные в JSON

В итоге запрос будет выглядеть так:

POST /users/add HTTP/1.1
HOST: dummyjson.com
Content-Type: application/json

{ "firstName": "Nik", "age": 20 }

Какие возможные варианты ответа от сервера:

• 201 - ресурс успешно создан
• 422 - ошибка валидации
• 406 - некорректные данные, например не тот формат

Подробнее о HTTP-кодах можно прочитать здесь. Большая часть из них может встречаться с любым HTTP-методом.

Обновление пользователя

Для обновления пользователя мы должны отправить PATCH запрос на эндпоинт https://dummyjson.com/users/{id}. Обновлять можно любой набор параметров, не обязательно сразу все.

PATCH /users/1 HTTP/1.1
HOST: dummyjson.com
Content-Type: application/json

{ "firstName": "Nina" }

Если все прошло успешно, то возможны два варианта ответа:

• Код 200 и какие-то данные, например JSON с обновленными данными ресурса
• Код 204, в том случае, если тела ответа нет

Удаление пользователя

Для удаления пользователя мы должны отправить DELETE запрос на эндпоинт https://dummyjson.com/users/{id}. Тела запроса в таком случае нет, так как все и так понятно из адреса запроса

DELETE /users/1 HTTP/1.1
HOST: dummyjson.com

Если все прошло успешно, то возможны два варианта ответа:

• Код 200 и какие-то данные
• Код 204 и пустое тело ответа

Идемпотентность

Когда мы работаем с API, очень важным становится понятие идемпотентности запросов. Это свойство, которое говорит о том насколько безопасно выполнять HTTP вызов повторно. Идемпотентный запрос приводит к одному и тому же результату независимо от количества сделанных вызовов.

Возьмем эндпоинт /users. Он возвращает список пользователей и ничего не меняет на сервере. Каждый новый вызов этого эндпоинта, возвращает идентичный список пользователей. Он идемпотентный. Список пользователей может поменяться если его меняют где-то в другом месте, но даже это не делает GET запрос на /users не идемпотентным. Главное что он сам ничего не меняет.

А вот POST-запрос не идемпотентный. Каждый вызов /users/add добавляет нового пользователя, хотя и с теми же самыми данными. Или возвращает ошибку, если, например, на сервере добавлена проверка на уникальность каких-то данных. Именно поэтому при отправке форм из браузера после нажатия f5, браузер всегда спрашивает точно ли мы хотим выполнить этот запрос повторно.

PATCH по стандарту тоже не идемпотентный, хотя на практике, чаще, его делают идемпотентным. Но на это уже не могут рассчитывать браузеры или веб-сервера, так как они не знают про специфику конкретных приложений.

Самое интересное это DELETE, он по стандарту идемпотентный. То есть повторное удаление уже удаленного ресурса должно возвращать код 204 по спецификации HTTP. На практике про это знает не так много программистов, поэтому, обычно, повторное удаление приводит к ошибке 404.

Идемпотентность закреплена за методами HTTP в его спецификации, но то насколько HTTP API соответствует этим правилам зависит уже от программистов разрабатывающих его.

Самостоятельная работа

Остались вопросы? Задайте их в разделе «Обсуждение»

Вам ответят команда поддержки Хекслета или другие студенты.