CRUD — HTTP API

• Добавление пользователя
• Обновление пользователя
• Удаление пользователя
• Идемпотентность

В программировании часто используется аббревиатура CRUD. Она обозначает четыре базовых операции над информацией:

• Создание
• Чтение
• Обновление
• Удаление

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

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

Посмотрим на пример данных:

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

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

Давайте вернемся к примеру выше и обратим внимание на использование методов HTTP. У методов есть определенный смысл:

• GET нужен для извлечения данных
• POST — для создания и отправки форм
• PATCH — для обновления
• DELETE — для удаления

При этом URL часто остается одним и тем же.

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

Кеширование — это такая техника, которая позволяет веб-серверу или прокси сохранить ответ от сервера и отдавать его при следующих запросах без обращения к самому серверу.

Кеширование ускоряет доступ к ресурсам и разгружает серверы. Запрос GET можно кешировать для ускорения доступа, потому что GET никогда не меняет данные.

Методы POST, PATCH и DELETE кешировать нельзя — они должны постоянно приходить на сервер, так как они вносят изменения.

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

Попробуем добавить пользователя. Для этого по документации Dummy JSON нам нужно отправить POST-запрос на эндпоинт https://dummyjson.com/users/add.

Данные можно отправлять в разных форматах, HTML-формой или JSON-файлом. Чтобы использовать JSON, во время подготовки запроса нужно выполнить два шага:

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

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

POST /users/add HTTP/1.1
HOST: dummyjson.com
Content-Length: 33
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-Length: 23
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 имеет два исхода:

• добавляет нового пользователя, хотя и с теми же самыми данными
• возвращает ошибку, если на сервере добавлена проверка на уникальность каких-то данных

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

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

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

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

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

openssl s_client -connect dummyjson.com:443

---

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

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

Об обучении на Хекслете

• Статья «Как учиться и справляться с негативными мыслями»
• Статья «Ловушки обучения»
• Статья «Сложные простые задачи по программированию»
• Вебинар «Как самостоятельно учиться»