Типы запросов в FastAPI

FastAPI поддерживает все стандартные HTTP-методы (типы запросов), позволяя создавать полноценные RESTful API. Рассмотрим основные типы запросов, их предназначение, примеры использования в FastAPI и то, как они отображаются в автоматически генерируемой документации Swagger UI.

1. Основные типы запросов (HTTP-методы):

GET: Используется для получения (чтения) ресурса. GET-запросы не должны изменять состояние сервера. Они идемпотентны (повторные запросы с теми же параметрами должны возвращать тот же результат).
POST: Используется для создания нового ресурса. Часто используется для отправки данных на сервер (например, данных формы). POST-запросы могут изменять состояние сервера.
PUT: Используется для полной замены существующего ресурса. PUT-запросы идемпотентны. Клиент отправляет полное представление ресурса.
PATCH: Используется для частичного обновления существующего ресурса. PATCH-запросы не обязаны быть идемпотентными. Клиент отправляет только те поля, которые нужно изменить.
DELETE: Используется для удаления ресурса. DELETE-запросы идемпотентны.
OPTIONS: Используется для получения информации о доступных методах и других параметрах для указанного ресурса. Полезен для CORS (Cross-Origin Resource Sharing).
HEAD: Аналогичен GET, но сервер возвращает только заголовки ответа, без тела. Используется для получения метаданных о ресурсе (например, размер, тип содержимого) без загрузки самого ресурса.
TRACE: предназначен для диагностирования.

2. Примеры использования в FastAPI (без Pydantic):

python

from fastapi import FastAPI, Path, Query, Header
from typing import List, Optional, Dict, Union

app = FastAPI()

# --- GET ---
@app.get("/items/{item_id}")
async def read_item(item_id: int = Path(..., title="The ID of the item to get"),
                    q: Optional[str] = Query(None, max_length=50)):
    """
    Получает элемент по его ID.

    - **item_id**: ID элемента (целое число).
    - **q**: Необязательный параметр запроса (строка).
    """
    return {"item_id": item_id, "q": q}

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10) -> List[Dict[str, Union[str, int]]]:
    """
    Получает список элементов с пагинацией.

    - **skip**: Сколько элементов пропустить (по умолчанию 0).
    - **limit**: Максимальное количество элементов (по умолчанию 10).
    """
    fake_items_db = [
        {"item_name": "Foo", "item_id": 1},
        {"item_name": "Bar", "item_id": 2},
        {"item_name": "Baz", "item_id": 3},
    ]
    return fake_items_db[skip : skip + limit]

# --- POST ---
@app.post("/items/")
async def create_item(item: Dict[str, Union[str, int, float]]):
    """
    Создает новый элемент.

    Тело запроса должно быть словарем (JSON) с произвольными ключами (строки)
    и значениями, которые могут быть строками, целыми числами или числами с плавающей точкой.
    **Внимание:** Валидация структуры словаря очень ограничена без Pydantic!
    """
    return item

# --- PUT ---
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Dict[str, Union[str, int, float]]):
    """
    Полностью обновляет элемент с заданным ID.

    - **item_id**: ID элемента (целое число).
    - **item**:  Словарь (JSON) с *полным* новым представлением элемента.
      **Внимание:** Валидация структуры словаря очень ограничена без Pydantic!
    """
    return {"item_id": item_id, "updated_item": item}

# --- PATCH ---
@app.patch("/items/{item_id}")
async def partial_update_item(item_id: int, item: Dict[str, Union[str, int, float]]):
    """
    Частично обновляет элемент с заданным ID.

    - **item_id**: ID элемента (целое число).
    - **item**: Словарь (JSON) с полями, которые нужно обновить.
      **Внимание:** Валидация структуры словаря очень ограничена без Pydantic!
    """
    return {"item_id": item_id, "partially_updated_item": item}

# --- DELETE ---
@app.delete("/items/{item_id}")
async def delete_item(item_id: int):
    """
    Удаляет элемент с заданным ID.

    - **item_id**: ID элемента (целое число).
    """
    return {"message": f"Item {item_id} deleted"}

# --- OPTIONS ---
@app.options("/items/{item_id}")
async def options_item(item_id: int):
    """
    Возвращает информацию о доступных методах для элемента.
    """
    # FastAPI автоматически обрабатывает OPTIONS-запросы,
    # но вы можете добавить свою логику, если нужно.
    return {"allowed_methods": ["GET", "PUT", "PATCH", "DELETE", "OPTIONS"]}

# --- HEAD ---
@app.head("/items/{item_id}")
async def head_item(item_id: int):
    """
    Возвращает заголовки ответа для элемента (без тела).
    """
    # FastAPI автоматически обрабатывает HEAD-запросы, основываясь на GET-обработчике.
    #  Вам не нужно писать отдельную логику, если только вы не хотите
    #  вернуть какие-то специфические заголовки.
    return  # Пустое тело ответа

# --- TRACE ---
@app.trace("/items/{item_id}")
async def trace_item(item_id: int):
    """
    Трассировка запроса
    """
    return {"item_id": item_id}

# --- Custom Headers ---
@app.get("/headers/")
async def read_headers(user_agent: Optional[str] = Header(None)):
    """
    Пример получения заголовка User-Agent.

    - **user_agent**:  Заголовок User-Agent (необязательный).
    """
    return {"User-Agent": user_agent}

3. Разбор примера и отображение в Swagger UI:

GET (/items/{item_id}, /items/):
- Swagger UI: Отображает параметры пути (item_id), параметры запроса (q, skip, limit), их типы, описания (если есть) и примеры. Для /items/ Swagger UI покажет, что ожидается список словарей в ответе. Кнопка "Try it out" позволит отправить запрос и увидеть результат.
POST (/items/):
- Swagger UI: Покажет, что ожидается тело запроса в формате JSON (object). Но без детальной схемы! Вам придется вручную ввести JSON, и FastAPI проверит только, что это в принципе словарь. Нет проверки ключей и типов значений внутри словаря.
PUT (/items/{item_id}):
- Swagger UI: Аналогично POST, но с указанием, что это PUT-запрос. Также нет детальной валидации тела запроса.
PATCH (/items/{item_id}):
- Swagger UI: Аналогично POST и PUT, но с указанием, что это PATCH-запрос. Также нет детальной валидации тела запроса.
DELETE (/items/{item_id}):
- Swagger UI: Отображает параметр пути item_id и тип запроса DELETE.
OPTIONS (/items/{item_id}):
- Swagger UI: Покажет, что это OPTIONS-запрос. Если вы не переопределили обработчик, Swagger UI покажет стандартный ответ FastAPI

Типы запросов в FastAPI: Подробное руководство с примерами и Swagger

FastAPI — современный фреймворк для создания API на Python, который поддерживает все стандартные HTTP-методы. В этой статье мы рассмотрим основные типы запросов (GET, POST, PUT, DELETE, PATCH), их использование, примеры реализации и отображение в Swagger UI.

1. HTTP-методы и их назначение

GET

Используется для получения данных. Параметры передаются через путь URL или query-строку.

POST

Предназначен для создания новых ресурсов. Данные передаются в теле запроса (JSON, формы).

PUT

Применяется для полного обновления существующего ресурса. Требует передачи всех полей.

DELETE

Удаляет указанный ресурс.

PATCH

Используется для частичного обновления ресурса. Можно передать только изменяемые поля.

2. Реализация запросов в FastAPI

Примеры кода

GET-запрос

python

from fastapi import FastAPI

app = FastAPI()

# Path-параметр и query-параметр
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query": q}

Swagger:

Параметр item_id в пути URL, q — опциональный query-параметр.

POST-запрос

python

from fastapi import Body

@app.post("/items/")
async def create_item(item: dict = Body(...)):
    return {"item": item}

Swagger:

Тело запроса в формате JSON.

POST с формой

python

from fastapi import Form

@app.post("/login/")
async def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

Swagger:

Поля формы username и password.

PUT-запрос

python

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: dict = Body(...)):
    return {"item_id": item_id, "updated_item": item}

Swagger:

Тело запроса для полного обновления.

DELETE-запрос

python

@app.delete("/items/{item_id}")
async def delete_item(item_id: int):
    return {"message": f"Item {item_id} удален"}

Swagger:

Удаление по item_id в пути.

PATCH-запрос

python

@app.patch("/items/{item_id}")
async def partial_update(item_id: int, item: dict = Body(...)):
    return {"item_id": item_id, "patched_fields": item}

Swagger:

Частичное обновление через тело запроса.

3. Типы параметров запросов

Path-параметры

Определяются в пути URL:

python

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"user_id": user_id}

Query-параметры

Передаются в URL после ?:

python

@app.get("/search")
async def search(query: str, limit: int = 10):
    return {"query": query, "limit": limit}

Тело запроса (Body)

Используется для POST, PUT, PATCH:

python

@app.post("/data")
async def process_data(data: dict = Body(...)):
    return {"received_data": data}

Формы (Form)

Для данных из HTML-форм:

python

@app.post("/submit-form")
async def submit_form(name: str = Form(...), age: int = Form(...)):
    return {"name": name, "age": age}

4. Отображение в Swagger UI

FastAPI автоматически генерирует документацию Swagger по адресу /docs:

Каждый метод отображается с примером запроса.
Параметры пути, query, body и формы разделены по вкладкам.
Можно тестировать API прямо в интерфейсе.

5. Другие HTTP-методы

FastAPI поддерживает и менее распространенные методы:

HEAD

Аналогичен GET, но без тела ответа:

python

@app.head("/items/{item_id}")
async def head_item(item_id: int):
    return

OPTIONS

Возвращает информацию о доступных методах:

python

@app.options("/items/{item_id}")
async def options_item():
    return {"Allow": "GET, POST, PUT, DELETE"}

Заключение

FastAPI предоставляет удобный синтаксис для работы с различными типами запросов. Без использования Pydantic вы можете опираться на стандартные типы Python и параметры (Body, Form, Query). Swagger UI автоматически документирует все endpoints, упрощая тестирование и интеграцию.

Типы запросов в FastAPI ​

1. Основные типы запросов (HTTP-методы): ​

Типы запросов в FastAPI: Подробное руководство с примерами и Swagger ​

1. HTTP-методы и их назначение ​

GET ​

POST ​

PUT ​

DELETE ​

PATCH ​

2. Реализация запросов в FastAPI ​

Примеры кода ​

GET-запрос ​

POST-запрос ​

POST с формой ​

PUT-запрос ​

DELETE-запрос ​

PATCH-запрос ​

3. Типы параметров запросов ​

Path-параметры ​

Query-параметры ​

Тело запроса (Body) ​

Формы (Form) ​

4. Отображение в Swagger UI ​

5. Другие HTTP-методы ​

HEAD ​

OPTIONS ​

Заключение ​

Типы запросов в FastAPI

1. Основные типы запросов (HTTP-методы):

Типы запросов в FastAPI: Подробное руководство с примерами и Swagger

1. HTTP-методы и их назначение

GET

POST

PUT

DELETE

PATCH

2. Реализация запросов в FastAPI

Примеры кода

GET-запрос

POST-запрос

POST с формой

PUT-запрос

DELETE-запрос

PATCH-запрос

3. Типы параметров запросов

Path-параметры

Query-параметры

Тело запроса (Body)

Формы (Form)

4. Отображение в Swagger UI

5. Другие HTTP-методы

HEAD

OPTIONS

Заключение