← Все статьи
DEO CORE JOURNAL Backend и DevOps

Как создать REST API: контракт до обработчиков

Редакция DEO CORE19 ноября 2026 г.2 min

REST API стоит начинать с договора между клиентом и сервером. Для сервиса заявок определите поля, обязательность, состояния и ошибки. Если сначала написать обработчики, эти решения всё равно появятся, но будут разбросаны по коду.

Назовите ресурсы и операции

Для заявок подойдут GET /requests/, POST /requests/, GET /requests/{id}/ и PATCH /requests/{id}/. Список должен иметь ограничение размера и понятную пагинацию. Уточните, какие поля можно менять после создания.

Создание обычно возвращает 201 и представление новой записи. Для неверных данных выберите согласованный формат ошибки. Не возвращайте 200 с текстом «ошибка» внутри успешного ответа: клиенту и наблюдению за сервисом сложнее различать исходы.

Проверьте доступ к каждой записи

Авторизация запроса отвечает на вопрос, кто обращается. Проверка объекта — имеет ли этот пользователь право читать или менять конкретную заявку. Одного скрытого пункта меню недостаточно: идентификатор можно подставить вручную.

Не принимайте поля владельца и внутренних статусов без отдельной проверки. Разрешённые поля входного запроса лучше задавать явно.

Определите поведение повторов

Мобильный клиент может повторить запрос после обрыва, хотя сервер уже создал запись. Для важных операций используйте продуманную идемпотентность: ключ операции, сохранённый результат и правило обработки повторного обращения. Уникальность в базе должна поддерживать выбранное правило.

Проверьте создание, пустые поля, чужой объект, повторный запрос и неизвестный идентификатор. Документация должна содержать не только счастливый пример, но и типовые ошибки.

Начальную реализацию можно собрать по FastAPI tutorial. Хранение и ограничения данных разобраны в статье о PostgreSQL.