Создание ресурса: POST и статус 201

В предыдущем уроке RoomIn описывала входные данные, а RoomOut отбирала публичные поля ответа. Обработчик возвращал демонстрационную карточку без сохранения. Чтобы созданную переговорную можно было затем прочитать через GET, обработчикам нужно общее хранилище.

status_code=201: статус успешного создания

HTTP разделяет два разных успеха: 200 означает «запрос выполнен», а 201 — «запрос выполнен и ресурс создан». Если POST-обработчик просто возвращает данные без явного статуса, FastAPI отвечает 200. В нашем API создание переговорной должно возвращать 201: ответ 200 не соответствует этому выбранному контракту. Сам по себе статус 200 у POST не является нарушением HTTP — POST может выполнять и другие действия.

Чтобы изменить статус, в декоратор добавляют параметр status_code:

@app.post("/api/rooms", response_model=RoomOut, status_code=201)
def create_room(room: RoomIn):
    ...

Теперь при успешном завершении функции FastAPI отправит статус 201, а не 200.

Важно понимать, что status_code=201 — это только инструкция для ответа. Он говорит клиенту, что ресурс создан, но сам по себе не сохраняет никаких данных. Если тело функции не добавит запись в какое-то хранилище, ответ придёт с кодом 201, но при следующем GET записи не окажется. Статус декларирует намерение; реализацию хранения берёт на себя обработчик.