Код статусу відповіді

Так само, як ви можете вказати модель відповіді, ви також можете оголосити HTTP код статусу, що використовується для відповіді, за допомогою параметра status_code в будь-якій з операцій шляху:

• @app.get()
• @app.post()
• @app.put()
• @app.delete()
• тощо.

Python 3.9+

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, наприклад, Python http.HTTPStatus.

Він буде:

• Повертати цей код статусу у відповіді.
• Документувати його як такий у схемі OpenAPI (і, таким чином, в інтерфейсах користувача):

Примітка

Деякі коди відповіді (див. наступний розділ) вказують, що відповідь не має тіла.

FastAPI знає про це і створить документацію OpenAPI, яка вказує, що тіла відповіді немає.

Про HTTP коди статусу

Примітка

Якщо ви вже знаєте, що таке HTTP коди статусу, перейдіть до наступного розділу.

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

Ці коди статусу мають пов’язану назву для їх розпізнавання, але важливою частиною є число.

Коротко:

• 100 - 199 — для «Information». Ви рідко використовуєте їх напряму. Відповіді з такими кодами статусу не можуть мати тіла.
• 200 - 299 — для «Successful» відповідей. Це ті, які ви використовуватимете найчастіше.
  • 200 — код статусу за замовчуванням, який означає, що все було «OK».
  • Інший приклад — 201, «Created». Його зазвичай використовують після створення нового запису в базі даних.
  • Особливий випадок — 204, «No Content». Цю відповідь використовують, коли немає вмісту для повернення клієнту, і тому відповідь не повинна мати тіла.
• 300 - 399 — для «Redirection». Відповіді з цими кодами статусу можуть мати або не мати тіла, за винятком 304, «Not Modified», яка не повинна мати тіла.
• 400 - 499 — для відповідей «Client error». Це другий тип, який ви, ймовірно, будете використовувати найчастіше.
  • Приклад — 404, для відповіді «Not Found».
  • Для загальних помилок з боку клієнта ви можете просто використовувати 400.
• 500 - 599 — для помилок сервера. Ви майже ніколи не використовуєте їх напряму. Коли щось піде не так у якійсь частині коду вашого застосунку або на сервері, автоматично буде повернено один із цих кодів статусу.

Порада

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

Скорочення, щоб запам’ятати назви

Розглянемо попередній приклад ще раз:

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


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

201 — це код статусу для «Created».

Але вам не потрібно запам'ятовувати, що означає кожен із цих кодів.

Ви можете використовувати зручні змінні з fastapi.status.

Python 3.9+

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.

FastAPI надає той самий starlette.status як fastapi.status просто як зручність для вас, розробника. Але він походить безпосередньо зі Starlette.

Зміна значення за замовчуванням

Пізніше, у Посібнику для досвідчених користувачів, ви побачите, як повертати інший код статусу, ніж значення за замовчуванням, яке ви оголошуєте тут.