HTTP коды статуса ответа¶

Вы можете задать HTTP код статуса ответа с помощью параметра status_code подобно тому, как вы определяете схему ответа в любой из операций пути:

@app.get()
@app.post()
@app.put()
@app.delete()
и других.


from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

Примечание

Обратите внимание, что status_code является атрибутом метода-декоратора (get, post и т.д.), а не функции-обработчика пути в отличие от всех остальных параметров и тела запроса.

Параметр status_code принимает число, обозначающее HTTP код статуса ответа.

Информация

В качестве значения параметра status_code также может использоваться IntEnum, например, из библиотеки http.HTTPStatus в Python.

Это позволит:

Возвращать указанный код статуса в ответе.
Документировать его как код статуса ответа в OpenAPI схеме (а значит, и в пользовательском интерфейсе):

Примечание

Некоторые коды статуса ответа (см. следующий раздел) указывают на то, что ответ не имеет тела.

FastAPI знает об этом и создаст документацию OpenAPI, в которой будет указано, что тело ответа отсутствует.

Об HTTP кодах статуса ответа¶

Примечание

Если вы уже знаете, что представляют собой HTTP коды статуса ответа, можете перейти к следующему разделу.

В протоколе HTTP числовой код состояния из 3 цифр отправляется как часть ответа.

У кодов статуса есть названия, чтобы упростить их распознавание, но важны именно числовые значения.

Кратко о значениях кодов:

1XX – статус-коды информационного типа. Они редко используются разработчиками напрямую. Ответы с этими кодами не могут иметь тела.
2XX – статус-коды, сообщающие об успешной обработке запроса. Они используются чаще всего.
- 200 – это код статуса ответа по умолчанию, который означает, что все прошло "OK".
- Другим примером может быть статус 201, "Created". Он обычно используется после создания новой записи в базе данных.
- Особый случай – 204, "No Content". Этот статус ответа используется, когда нет содержимого для возврата клиенту, и поэтому ответ не должен иметь тела.
3XX – статус-коды, сообщающие о перенаправлениях. Ответы с этими кодами статуса могут иметь или не иметь тело, за исключением ответов со статусом 304, "Not Modified", у которых не должно быть тела.
4XX – статус-коды, сообщающие о клиентской ошибке. Это ещё одна наиболее часто используемая категория.
- Пример – код 404 для статуса "Not Found".
- Для общих ошибок со стороны клиента можно просто использовать код 400.
5XX – статус-коды, сообщающие о серверной ошибке. Они почти никогда не используются разработчиками напрямую. Когда что-то идет не так в какой-то части кода вашего приложения или на сервере, он автоматически вернёт один из 5XX кодов.

Подсказка

Чтобы узнать больше о HTTP кодах статуса и о том, для чего каждый из них предназначен, ознакомьтесь с документацией MDN об HTTP кодах статуса ответа.

Краткие обозначения для запоминания названий кодов¶

Рассмотрим предыдущий пример еще раз:


from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

201 – это код статуса "Создано".

Но вам не обязательно запоминать, что означает каждый из этих кодов.

Для удобства вы можете использовать переменные из fastapi.status.


from fastapi import FastAPI, status

app = FastAPI()


@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}

Они содержат те же числовые значения, но позволяют использовать подсказки редактора для выбора кода статуса:

Технические детали

Вы также можете использовать from starlette import status вместо from fastapi import status.

FastAPI позволяет использовать как starlette.status, так и fastapi.status исключительно для удобства разработчиков. Но поставляется fastapi.status непосредственно из Starlette.

Изменение кода статуса по умолчанию¶

Позже, в Руководстве для продвинутых пользователей, вы узнаете, как возвращать HTTP коды статуса, отличные от используемого здесь кода статуса по умолчанию.