Обробка POST-запитів: відправка даних

POST-запити використовують для передачі даних на сервер. Цей метод зазвичай застосовують для створення нових ресурсів, наприклад, додавання запису в базу даних. На відміну від GET-запитів, які передають дані в URL, POST відправляє дані в тілі запиту — тому він підходить для більш складних структур.

---

Приклад базового POST-запиту

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

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# Визначаємо модель даних
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool

# Ендпоінт для обробки POST-запитів
@app.post("/items/")
async def create_item(item: Item):
    return {
        "message": "Item has been created!",
        "item": item
    }

Тепер, якщо ти запустиш сервер за допомогою uvicorn main:app --reload і відправиш POST-запит на /items/, передавши JSON-дані, сервер поверне ці дані назад з повідомленням. Можеш спробувати через Swagger UI (доступно за адресою http://127.0.0.1:8000/docs) або через інструмент на кшталт Postman.

Наприклад:

POST /items/
{
    "name": "Laptop",
    "price": 799.99,
    "is_offer": true
}

Відповідь:

{
    "message": "Item has been created!",
    "item": {
        "name": "Laptop",
        "price": 799.99,
        "is_offer": true
    }
}

---

Як передавати дані в POST-запитах

FastAPI використовує моделі даних Pydantic для валідації і серіалізації даних. Це робить передачу й обробку даних неймовірно зручною й безпечною.

Обробка даних прямо з тіла запиту без перевірки може призвести до помилок або навіть вразливостей. З Pydantic ми можемо задати суворі вимоги до структури й типів даних, що допомагає уникнути проблем.

Додавання значень за замовчуванням і перевірка типів

У Pydantic ти можеш задавати значення за замовчуванням і робити базову валідацію даних. Наприклад:

class Item(BaseModel):
    name: str
    price: float = 0.0  # Значення за замовчуванням
    is_offer: bool = False

Тепер, якщо клієнт забуде передати price або is_offer, ти все одно отримаєш коректну відповідь, бо значення підставляться автоматично.

Спробуй надіслати такий запит:

POST /items/
{
    "name": "Smartphone"
}

Відповідь:

{
    "message": "Item has been created!",
    "item": {
        "name": "Smartphone",
        "price": 0.0,
        "is_offer": false
    }
}

---

Валідація і обробка даних

Додамо трохи магії в наш API! FastAPI і Pydantic підтримують складні перевірки даних, включаючи регулярні вирази, мінімальні і максимальні значення, довжини рядків і багато іншого.

Приклад більш складної моделі

Припустимо, ми хочемо, щоб назва товару мала довжину не менше 3 символів, а ціна — була строго додатним числом.

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(min_length=3, max_length=50)
    price: float = Field(gt=0)  # Ціна має бути більше 0
    is_offer: bool = Field(default=False)

Тепер, якщо хтось спробує відправити дані з некоректною назвою або від'ємною ціною, FastAPI автоматично поверне помилку:

POST /items/
{
    "name": "12",
    "price": -10.5,
    "is_offer": true
}

Відповідь:

{
    "detail": [
        {
            "loc": ["body", "price"],
            "msg": "ensure this value is greater than 0",
            "type": "value_error.number.not_gt"
        },
        {
            "loc": ["body", "name"],
            "msg": "ensure this value has at least 3 characters",
            "type": "value_error.any_str.min_length"
        }
    ]
}

Зауваж, нам не довелося робити купу ручної роботи, щоб реалізувати цю систему перевірок. Ось чому FastAPI такий потужний.

---

Обробка кількох елементів

Іноді треба обробити масив даних. Наприклад, коли клієнт відправляє список товарів для масового додавання.

Приклад: масив об'єктів

Можемо легко обробити масив за допомогою анотації типів List з модуля typing.

Ось приклад:

from typing import List

@app.post("/items/bulk/")
async def create_items(items: List[Item]):
    return {
        "message": f"{len(items)} items have been created!",
        "items": items
    }

Спробуй відправити такий запит:

POST /items/bulk/
[
    {
        "name": "Tablet",
        "price": 499.99,
        "is_offer": false
    },
    {
        "name": "Monitor",
        "price": 199.99,
        "is_offer": true
    }
]

Відповідь:

{
    "message": "2 items have been created!",
    "items": [
        {
            "name": "Tablet",
            "price": 499.99,
            "is_offer": false
        },
        {
            "name": "Monitor",
            "price": 199.99,
            "is_offer": true
        }
    ]
}

Хіба це не магія? FastAPI сам розпарсить JSON-масив і перевірить кожен об'єкт на відповідність моделі Item.

---

Типові помилки

Обробка даних може бути примхливою, якщо ти не врахував усі аспекти. Наприклад, часто забувають:

1. Вказувати правильні типи даних у моделі. Якщо очікується int, а клієнт передає str, це викличе помилку.
2. Перевіряти мінімальні і максимальні значення чисел. Нікому не потрібен товар з ціною -1000000.
3. Працювати з масивами об'єктів, коректно перевіряючи кожен елемент. FastAPI зробить це за тебе, але тільки при правильній конфігурації.

Якщо API повертає помилку 422, швидше за все, проблема в невідповідності даних, які клієнт відправив, і очікуваних параметрів моделі.

---

Як це виглядає в реальних проєктах

Обробка POST-запитів найчастіше використовується для створення нових даних. Приклади реального застосування:

• Реєстрація нового користувача (передача імені, пошти, пароля).
• Додавання товарів в інтернет-магазині.
• Збереження даних форми зворотнього зв'язку.

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

---

Ти готовий до наступного кроку! Далі ми продовжимо розкривати міць FastAPI, вивчаючи PUT-запити і оновлення даних. Не забудь закріпити матеріал — адже обробка POST — це основа будь-якої системи керування даними.