Что принимать на вход и возвращать в ответе для каждого CRUD-метода?

Входные данные и ответы CRUD-методов

• Create (POST):
• на вход принимается объект с данными нового ресурса в формате валидного JSON

в ответе возвращается созданный объект с новым уникальным ID и статусом 201

Read (GET):

• на вход передаётся идентификатор ресурса либо параметры фильтрации

в ответе приходит объект или набор объектов с запрошенными данными и статусом 200

Update (PUT/PATCH):

• на вход подаются идентификатор ресурса и объект с изменениями: PUT заменяет его полностью, а PATCH вносит частичные изменения

в ответе возвращается обновлённый объект либо подтверждение операции со статусом 200/204

Delete (DELETE):

• на вход передаётся идентификатор ресурса

в ответе отправляется подтверждение удаления; часто это пустой ответ со статусом 204

Важно: HTTP-статус в ответе должен однозначно показывать результат выполненной операции

• Для обмена данными в API обычно используется формат JSON
• Ошибки и валидация обрабатываются с помощью соответствующих кодов и сообщений

Развёрнутый ответ

Основной ответ

Для каждого CRUD-метода — Create, Read, Update и Delete — необходимо заранее определить состав входных данных и формат ответа. Это делает поведение API однозначным и предсказуемым.

• Create: клиент отправляет объект с полями, необходимыми для создания ресурса, например JSON с его атрибутами. В ответ API обычно возвращает созданный объект, дополняя его уникальным идентификатором (ID) и метаданными, такими как даты создания и версии.
• Read: запрос содержит ID ресурса или параметры фильтрации и поиска. Ответом становится найденный объект либо список объектов; если ресурс отсутствует, возвращается ошибка.
• Update: запрос включает ID ресурса и поля, которые требуется изменить, — частичный или полный объект. В ответ можно получить обновлённый объект либо подтверждение успешного выполнения операции.
• Delete: запросу нужен ID ресурса. Обычно API возвращает подтверждение удаления, например статус 204 No Content; в некоторых случаях дополнительно передаётся удалённый объект или метаинформация.

Основные аспекты

• Данные, поступающие для Create и Update, необходимо проверять, чтобы исключить появление неконсистентных записей.
• В ответах полезно передавать не только сами данные, но и метаинформацию — временные метки и версии. Это упрощает дальнейшую работу с ресурсом, особенно в RESTful API.
• Ошибки, например 404 при обращении через Read/Delete к отсутствующему ресурсу или 400 при некорректных данных, должны обрабатываться единообразно и возвращаться клиенту в понятном формате.

Практический пример

В современных REST API для каждого метода обычно задают чёткий контракт JSON-схемы входных данных и стандартизированный формат ответа. Например, в приложении на PostgreSQL + Node.js (Express) endpoint Create принимает JSON с обязательными полями, а возвращает объект с ID и HTTP статусом 201 Created. Такой подход упрощает интеграцию и автоматическое тестирование.