Создание собственного API на Python (FastAPI): Гайд по POST, PUT, DELETE запросам и моделям Pydantic

Друзья, приветствую вас в очередной статье, посвященной разработке API с использованием фреймворка FastAPI. В прошлой публикации мы познакомились с основами FastAPI и написали первые функции, освоив GET-запросы. Однако возможности HTTP общения клиента и сервера этим не ограничиваются. Сегодня мы изучим POST, PUT и DELETE запросы.

В прошлой статье мы рассмотрели GET запросы и научились писать свои первые функции. Сегодня же мы рассмотрим методы, позволяющие отправлять данные (POST), обновлять (PUT) и удалять данные (DELETE).

Для того чтобы эти операции были не только возможны, но и выполнялись правильно и эффективно, необходимо использовать модели.

Что такое модели в FastApi?

Модель в FastAPI — это нечто вроде схемы или шаблона, который описывает структуру данных, с которыми работает ваше приложение. Проще говоря, это способ сказать: "Вот как должны выглядеть данные, которые мы принимаем или отправляем."

Основные задачи моделей в FastAPI:

1. Валидация данных: С помощью Pydantic мы можем проверять, что данные соответствуют ожидаемому формату. Например, если нам нужен объект пользователя с именем и возрастом, модель проверит, что имя — это строка, а возраст — число.

2. Документирование данных: Модели помогают автоматически создавать документацию для вашего API. Клиенты могут легко понять, какие данные они должны отправить или могут ожидать в ответе.

3. Работа с базами данных: Модели можно использовать для описания структуры данных в базе данных. Например, с помощью библиотек, таких как SQLAlchemy, мы можем создавать модели, которые напрямую связываются с таблицами в базе данных.

Корректно описывая собственные модели, вы, в первую очередь, облегчите пользователям вашего API понимание того, какие данные необходимо отправлять и ожидать в ответ. Это значительно упрощает интеграцию и использование вашего API, делая его более интуитивно понятным и удобным.

Пример модели в FastAPI:

Представим, что мы создаём API для управления пользователями. Мы можем создать модель, описывающую пользователя (подробно рассмотрим далее, сейчас просто посмотрите на общий синтаксис):

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

Эта модель поможет нам:

• Проверить, что данные, отправляемые клиентом, содержат строку name и целое число age.

• Сгенерировать документацию, показывающую, что ожидается в запросах и ответах.

• Использовать эту модель для работы с базой данных, создавая таблицу для хранения пользователей.

Дополнительные возможности моделей:

• Преобразование данных: Модели могут автоматически преобразовывать данные. Например, строку, содержащую дату, можно автоматически преобразовать в объект даты.

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

• Документация и примеры: Модели могут включать описание полей и примеры данных, что улучшает документацию вашего API.

Таким образом, модели в FastAPI являются мощным инструментом для обеспечения правильности, безопасности и удобства работы с данными в вашем приложении.

Pydantic

Pydantic — это библиотека, которая встроена в FastAPI и используется для работы с данными. Она помогает проверять и преобразовывать данные, чтобы они соответствовали нужным форматам. Когда вы создаете модели в FastAPI, вы фактически используете возможности Pydantic.

Бонусом, когда вы описываете свои модели через Pydantic и используете автодокументацию FastAPI (которую мы обсуждали в прошлой статье), ваша документация станет не только полезной, но и читабельной.

Представьте, что даже ваши бабушка и кот смогут разобраться, как пользоваться вашим API. И что самое приятное, вам не придётся краснеть за свою работу на встречах с коллегами или перед заказчиками. Всё будет выглядеть так, как будто вы — настоящий гуру API-разработки!

Что делает Pydantic:

1. Валидация данных: Pydantic проверяет, что данные соответствуют ожидаемым типам. Например, если вы ожидаете строку, а вам прислали число, Pydantic выдаст ошибку.

2. Преобразование данных: Он может автоматически преобразовывать данные. Например, если вы ожидаете дату, а получили строку, Pydantic попытается преобразовать эту строку в дату.

3. Документирование данных: Pydantic позволяет добавлять описания к полям модели, что помогает в создании документации для API.

Модели в FastAPI, созданные с помощью Pydantic, играют ключевую роль. Они позволяют точно и безопасно описывать структуру данных, валидацию и приведение типов, что делает разработку API более предсказуемой и защищённой от ошибок. С помощью моделей мы можем задать строгие правила для входных и выходных данных, что значительно упрощает написание и поддержку кода.

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

POST запросы на практике

POST запросы — это один из основных типов HTTP-запросов, используемых для отправки данных на сервер. В отличие от GET-запросов, которые обычно используются для получения данных, POST-запросы отправляют данные, которые сервер должен обработать. На практике это чаще всего используется для создания новых записей в базе данных или отправки данных для обработки.

Два самых частых и понятных примера POST запросов:

1. Отправка данных после заполнения формы на сайте (например, форма регистрации):

В этом сценарии фронтенд-часть веб-приложения собирает данные, которые пользователь ввел в форме регистрации.

После клика на кнопку «ОТПРАВИТЬ», данные отправляются на бэкенд через POST-запрос. Бэкенд, настроенный для обработки запросов на определенном маршруте, ожидает получения этих данных.

С помощью Pydantic мы описываем, какие данные должны быть переданы, в каком формате и проверяем их корректность. Это позволяет нам убедиться, что данные соответствуют нашим ожиданиям, и пользователь имеет право их отправить (подробнее мы это рассмотрим в теме авторизации и JWT).

Пример POST-запроса для регистрации пользователя (тоже пока смотрим, подробнее разбирать начнем совсем скоро):

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class UserRegistration(BaseModel):
    username: str
    password: str
    email: str


@app.post("/register/")
async def register_user(user: UserRegistration):
    # Логика регистрации пользователя
    return {"message": "User registered successfully", "user": user}

2. Покупка товара в любом интернет-магазине:

Корзина в интернет-магазине представляет собой массив данных с описанием товаров. В корзине обычно содержится информация об ID товара, его количестве, цене, а также данные о пользователе и прочая сопутствующая информация.

После клика на кнопку «КУПИТЬ» данные отправляются на бэкенд через POST-запрос, где происходит обработка заказа: проверка наличия товаров на складе, расчёт итоговой стоимости, создание заказа в системе и отправка подтверждения пользователю.

Пример POST-запроса для покупки товара:

from fastapi import FastAPI
from pydantic import BaseModel
from typing import List

app = FastAPI()


class Item(BaseModel):
    item_id: int
    quantity: int


class Purchase(BaseModel):
    user_id: int
    items: List[Item]


@app.post("/purchase/")
async def create_purchase(purchase: Purchase):
    # Логика обработки покупки
    return {"message": "Покупка успешна!", "purchase": purchase}

Понимаю, что сейчас может быть не все понятно, но мы это совсем скоро исправим.

POST запросы на реальной практике

��сли вы читали мою прошлую статью по FastAPI, то знаете что мы создаем API для некоего университета. Мы с вами уже работали со студентами, получали по ним информацию по разным запросам.

Давайте теперь выступим в роли администратора API, который должен добавить студента в базу данных.

Для начала давайте напишем модель нашего студента. Напоминаю, что массивы выглядели так:

{
  "student_id": 1,
  "first_name": "Иван",
  "last_name": "Иванов",
  "date_of_birth": "1998-05-15",
  "email": "[e-mail]",
  "phone_number": "[phone]",
  "address": "г. Москва, ул. Пушкина, д. 10, кв. 5",
  "enrollment_year": 2017,
  "major": "Информатика",
  "course": 3,
  "special_notes": "Без особых примет"
}

Я предлагаю и далее придерживаться данной модели. Что мы тут видим?

Student_id – это целое число (int), как и enrollment_year и course. Но у них же есть ограничения, верно? Допустим наш админ решит по только ему ведомой причине написать, что студент в университет поступил в 1980, когда университет открылся в 2010, да ещё и на 7-й курс, когда курсов всего 5. Для того чтоб такое у нас не прошло мы и будем использовать Pydantic.

В Pydantic уже предусмотрены случаи, когда мы записываем диапазон допустимых значений. Например курс от 1 до 5 или год от 2010 до 2024. Далее мы посмотрим как оно работает.

Идем дальше. Что там у нас с остальными данными?

Есть у нас и специфические данные. К примеру это email. Через стандартный email: str мы не особо сильно сможем указать, что мы ждем emai, а не другую строку. Конечно, можно сильно заморочиться. Использовать регулярные выражения, писать запутанные валидаторы и прочее, но в этом смысла нет, ведь Pydantic уже многое придумал за нас, упростив нам жизнь.

В контексте email мы прямо с модуля Pydantic можем импортировать EmailStr, а после нам достаточно будет просто передать данный объект класса в описание поля Pydantic (совсем скоро рассмотрим на реальном примере, потерпите).

Некоторые поля, такие как «special_notes» нам, возможно, не захочется передавать явно и достаточно будет указать просто «Без особых примет» по умолчанию. Это нам тоже позволит сделать Pydantic.

Бывают случаи когда нам нужно выбрать из указанного значения. К примеру это факультеты. Мы знаем что в нашем университете, к примеру, 5 факультетов и, возможно, есть необходимость ограничить этот ввод данных. Тут, к сожалению, в самом Pydantic метода нет, но я вам покажу как можно легко обойти эту проблему без внутреннего валидатора.

А как быть, если Pydantic не имеет специального типа данных или у нас есть какая-то специфическая история с параметром? В этом случае нам на помощь прийдет внутренний валидатор Pydantic (рассмотрим как он работает на примере с телефоном).

Надеюсь, что вы поняли что у нас за проблема и зачем мы ее будем решать при помощи Pydantic. Начнем делать описание модели. Тут как обычно. Сначала полный код, а после пояснение кода.

from enum import Enum
from pydantic import BaseModel, EmailStr, Field, field_validator, ValidationError
from datetime import date, datetime
from typing import Optional
import re


class Student(BaseModel):
    student_id: int
    phone_number: str = Field(default=..., description="Номер телефона в международном формате, начинающийся с '+'")
    first_name: str = Field(default=..., min_length=1, max_length=50, description="Имя студента, от 1 до 50 символов")
    last_name: str = Field(default=..., min_length=1, max_length=50, description="Фамилия студента, от 1 до 50 символов")
    date_of_birth: date = Field(default=..., description="Дата рождения студента в формате ГГГГ-ММ-ДД")
    email: EmailStr = Field(default=..., description="Электронная почта студента")
    address: str = Field(default=..., min_length=10, max_length=200, description="Адрес студента, не более 200 символов")
    enrollment_year: int = Field(default=..., ge=2002, description="Год поступления должен быть не меньше 2002")
    major: Major = Field(default=..., description="Специальность студента")
    course: int = Field(default=..., ge=1, le=5, description="Курс должен быть в диапазоне от 1 до 5")
    special_notes: Optional[str] = Field(default=None, max_length=500,
                                         description="Дополнительные заметки, не более 500 символов")

    @field_validator("phone_number")
    @classmethod
    def validate_phone_number(cls, values: str) -> str:
        if not re.match(r'^\+\d{1,15}$', values):
            raise ValueError('Номер телефона должен начинаться с "+" и содержать от 1 до 15 цифр')
        return values

    @field_validator("date_of_birth")
    @classmethod
    def validate_date_of_birth(cls, values: date):
        if values and values >= datetime.now().date():
            raise ValueError('Дата рождения должна быть в прошлом')
        return values

Надеюсь, что не сильно страшно, но это и не важно. Сейчас разберемся.

Импорты:

from enum import Enum
from pydantic import BaseModel, EmailStr, Field, field_validator, ValidationError
from datetime import date, datetime
from typing import Optional
import re

• from enum import Enum: для создания перечислений (enums).

• from pydantic import BaseModel, EmailStr, Field, field_validator, ValidationError: Pydantic используется для создания моделей данных и валидации.

• from datetime import date, datetime: для работы с датами.

• from typing import Optional: для указания необязательных полей.

• import re: для использования регулярных выражений.

Перечисления, как вы поняли, нам будут нужны для того чтоб задать те факультеты, которые есть в нашем университете и это мы использовали в данном классе:

class Major(str, Enum):
    informatics = "Информатика"
    economics = "Экономика"
    law = "Право"
    medicine = "Медицина"
    engineering = "Инженерия"
    languages = "Языки"

Класс Major наследуется от str и Enum для обеспечения определенных функциональных возможностей.

Когда вы наследуете от str и Enum, вы создаете перечисление, где каждый член является строкой. Это позволяет использовать строки везде, где ожидается один из членов перечисления, и получать дополнительные возможности перечисления, такие как ограничение набора возможных значений и удобные методы для работы с этими значениями.

Синтаксис, как вы видите, достаточно простой, но, при этом, очень функциональный и я уверен, что использовать подобные записи вы будете часто.

Конечно, сам по себе класс Major нам не особо интересен и далее он будет использован в описании модели нашего студента.

Класс Student

Класс Student позволяет описывать студента и проверять корректность его данных. Он может быть использован в POST-запросах для проверки, что данные при добавления студента передаются корректно, а также для документирования API, чтобы правильно получать данные о студенте. Все это мы рассмотрим далее на конкретных примерах.

Сам класс можно разделить на две условные группы:

1. Описание полей (field)

2. Внутренние валидаторы

Класс всегда будет наследоваться от BaseModel.

Зачем это нужно?

Когда мы наследуем класс от BaseModel, это означает, что наш класс Student получает все функции и возможности, которые предоставляет Pydantic для работы с моделями данных.

Описание полей может быть, как максимально простым:

student_id: int

Так и с указанием параметров и условий:

phone_number: str = Field(default=..., description="Номер телефона в международном формате, начинающийся с '+'")

В данном случае мы использовали класс Field для описания поля. Данный класс в библиотеке Pydantic используется для добавления дополнительных метаданных к полям моделей, которые наследуются от BaseModel.

Обратите внимание. Тут мы использовали 2 параметра: default и description.

Тут все достаточно логично. Default = это то значение, которое в поле будет использоваться по умолчанию. Если мы передадим значение «…» аргументом этого параметра, то это будет значить, что данное значение обязательно.

В связи с этим, часто указание «default» игнорируется и запись начинается с …

phone_number: str = Field(..., description="Номер телефона в международном формате, начинающийся с '+'")

description в Field используется для предоставления описания поля. Это описание может быть использовано для генерации автоматической документации, подсказок в IDE (средах разработки) или для облегчения понимания назначения поля.

Теперь разберем более детальную валидацию поля.

first_name: str = Field(default=..., min_length=1, max_length=50, description="Имя студента, от 1 до 50 символов")

Тут вы видите 2 новых параметра: min_lenght и max_lenght. Не трудно догадаться, что тем самым мы описываем минимальную длину строки и максимальную длину строки.

То есть, если значение фамилии будет больше 50, то мы получим ошибку валидации.

course: int = Field(default=..., ge=1, le=5, description="Курс должен быть в диапазоне от 1 до 5")

Аббревиатуры ge и le в контексте библиотеки Pydantic используются для установки ограничений на числовые значения полей моделей данных. Давайте разберем, что они означают и почему используется именно такая аббревиатура.

ge и le в Pydantic

• ge: Это сокращение от "greater than or equal" (больше или равно). Используется для установки минимального допустимого значения для числового поля. Если значение поля меньше указанного, будет вызвано исключение валидации.

• le: Это сокращение от "less than or equal" (меньше или равно). Используется для установки максимального допустимого значения для числового поля. Если значение поля больше указанного, также будет вызвано исключение валидации.

В описании полей есть и другие значения. Далее я представил короткое описание некоторых параметров, которые достаточно часто используются в описании:

• title: Заголовок поля. Используется для документации или автоматической генерации API.

• examples: Примеры значений для поля. Используются для документации и обучения.

• gt, ge, lt, le: Ограничения для числовых значений (больше, больше или равно, меньше, меньше или равно).

• multiple_of: Число, на которое значение должно быть кратно.

• max_digits, decimal_places: Ограничения для чисел с плавающей точкой (максимальное количество цифр, количество десятичных знаков).

Больше информации вы можете получить в официальной документации Pydantic.

Вот полное описание каждого поля, которое относится к студенту:

student_id: int
phone_number: str = Field(default=..., description="Номер телефона в международном формате, начинающийся с '+'")
first_name: str = Field(default=..., min_length=1, max_length=50, description="Имя студента, от 1 до 50 символов")
last_name: str = Field(default=..., min_length=1, max_length=50, description="Фамилия студента, от 1 до 50 символов")
date_of_birth: date = Field(default=..., description="Дата рождения студента в формате ГГГГ-ММ-ДД")
email: EmailStr = Field(default=..., description="Электронная почта студента")
address: str = Field(default=..., min_length=10, max_length=200, description="Адрес студента, не более 200 символов")
enrollment_year: int = Field(default=..., ge=2002, description="Год поступления должен быть не меньше 2002")
major: Major = Field(default=..., description="Специальность студента")
course: int = Field(default=..., ge=1, le=5, description="Курс должен быть в диапазоне от 1 до 5")
special_notes: Optional[str] = Field(default=None, max_length=500,
                                     description="Дополнительные заметки, не более 500 символов")

Теперь вы понимаете что тут и к чему. Отлично. Теперь рассмотрим внутренние валидаторы.

@field_validator("phone_number")
@classmethod
def validate_phone_number(cls, values: str) -> str:
    if not re.match(r'^\+\d{1,15}$', values):
        raise ValueError('Номер телефона должен начинаться с "+" и содержать от 1 до 15 цифр')
    return values

@field_validator("date_of_birth")
@classmethod
def validate_date_of_birth(cls, values: date):
    if values and values >= datetime.now().date():
        raise ValueError('Дата рождения должна быть в прошлом')
    return values

Как вы видите, в моем примере есть 2 валидатора: тот, который проверяет корректность номера телефона и тот, который проверяет корректность даты рождения. Давай рассмотрим каждый.

Валидатор для номера телефона:

@field_validator("phone_number")
@classmethod
def validate_phone_number(cls, values: str) -> str:
    if not re.match(r'^+\d{1,15}$', values):
        raise ValueError('Номер телефона должен начинаться с "+" и содержать от 1 до 15 цифр')
    return values

Проверяет, что номер телефона начинается с "+" и содержит от 1 до 15 цифр. Для этого мы используем простое регулярное выражение.

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

Далее мы начинаем писать функцию. Так как это метод класса – первым аргументом мы передаем класс, а второй аргумент - это то значение, валидность, которого мы будем проверять.

Далее все просто или вернем значение, тем самым подтвердим, что данные валидны или вернем исключение.

Валидатор для даты рождения:

@field_validator("date_of_birth")
@classmethod
def validate_date_of_birth(cls, values: date):
    if values and values >= datetime.now().date():
        raise ValueError('Дата рождения должна быть в прошлом')
    return values

Проверяет, что дата рождения находится в прошлом.

Основные моменты:

• Pydantic: Обеспечивает валидацию и автоматическую сериализацию данных.

• Enum: Используется для ограничения значений специальности.

• Field: Определяет ограничения на поля, такие как минимальная/максимальная длина, описание и т.д.

• Validators: Пользовательские проверки данных (например, формат телефона и дата рождения)

Важный момент. Pydantic не обязательно использовать только в контексте FastApi, ведь это достаточно универсальная технология. К примеру, в следующих статьях, когда мы начнем рассматривать взаимодействие с базой данных через ORM мы так же будем использовать Pydantic.

Теперь, чтоб закрепить полученные знания, давайте протестируем наш класс на простых примерах (пока без привязки к FastApi). Напоминаю, что исходники кода по циклу статей про разработку собственного API вы найдете только в моем телеграмм канале.

Тестируем модель

Для начала напишем простую функцию. Принимать она будет словарь с данными о студенте. Далее, в результате, она будет или печатать ошибку или будет выводить информацию о студенте:

def test_valid_student(data: dict) -> None:
    try:
        student = Student(**data)
        print(student)
    except ValidationError as e:
        print(f"Ошибка валидации: {e}")

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

Для начала возьмем такие данные:

student_data = {
    "student_id": 1,
    "phone_number": "[phone]",
    "first_name": "Иван",
    "last_name": "Иванов",
    "date_of_birth": date(2000, 1, 1),
    "email": "[e-mail]",
    "address": "Москва, ул. Пушкина, д. Колотушкина",
    "enrollment_year": 1022,
    "major": "Информатика",
    "course": 3,
    "special_notes": "Увлекается программированием"
}

Вызовем функцию и посмотрим на результат:

Ошибка валидации:

1 validation error for Student

enrollment_year

Input should be greater than or equal to 2002 [type=greater_than_equal, input_value=1022, input_type=int]

Мы получаем ошибку, но нас Pydantic не оставляет в неведении. Он сообщает что мы передали год поступления 1022, а нужно было указать минимум 2002.

Исправим это значение:

student_data = {
    "student_id": 1,
    "phone_number": "[phone]",
    "first_name": "Иван",
    "last_name": "Иванов",
    "date_of_birth": date(2000, 1, 1),
    "email": "[e-mail]",
    "address": "Москва, ул. Пушкина, д. Колотушкина",
    "enrollment_year": 2022,
    "major": "Информатика",
    "course": 6,
    "special_notes": "Увлекается программированием"
}

Снова ошибка. Что не так? Смотрим:

Ошибка валидации: 1 validation error for Student

course

  Input should be less than or equal to 5 [type=less_than_equal, input_value=6, input_type=int]

К году поступления больше нет вопросов, а вот курс у нас указан 6-й, когда максимальный 5. Все понятно. Исправим.

student_data = {
    "student_id": 1,
    "phone_number": "[phone]",
    "first_name": "Иван",
    "last_name": "Иванов",
    "date_of_birth": date(2000, 1, 1),
    "email": "[e-mail]",
    "address": "Москва, ул. Пушкина, д. Колотушкина",
    "enrollment_year": 2022,
    "major": "Информатика",
    "course": 3,
    "special_notes": "Увлекается программированием"
}

student_id=1 phone_number='[phone]' first_name='Иван' last_name='Иванов' date_of_birth=datetime.date(2000, 1, 1) email='[e-mail]' address='Москва, ул. Пушкина, д. Колотушкина' enrollment_year=2022 major=<Major.informatics: 'Информатика'> course=3 special_notes='Увлекается программированием'

Результат мы получили такой, а значит все данные переданы корректно.

Теперь, чтоб убедиться что у нас корректно отрабатывает перечисление передадим факультет, которого не существует у нас.

student_data = {
    "student_id": 1,
    "phone_number": "[phone]",
    "first_name": "Иван",
    "last_name": "Иванов",
    "date_of_birth": date(2000, 1, 1),
    "email": "[e-mail]",
    "address": "Москва, ул. Пушкина, д. Колотушкина",
    "enrollment_year": 2022,
    "major": "Программирование",
    "course": 3,
    "special_notes": "Увлекается программированием"
}

Результат:

Input should be 'Информатика', 'Экономика', 'Право', 'Медицина', 'Инженерия' or 'Языки' [type=enum, input_value='Программирование', input_type=str]

Мы видим ошибку и говорит она о том, что мы не попали в перечисленные факультеты:

Доступные варианты: 'Информатика', 'Экономика', 'Право', 'Медицина', 'Инженерия' or 'Языки'

student_data = {
    "student_id": 1,
    "phone_number": "[phone]",
    "first_name": "Иван",
    "last_name": "Иванов",
    "date_of_birth": date(2000, 1, 1),
    "email": "[e-mail]",
    "address": "Москва, ул. Пушкина, д. Колотушкина",
    "enrollment_year": 2022,
    "major": "Информатика",
    "course": 3
}

Результат:

student_id=1 phone_number='[phone]' first_name='Иван' last_name='Иванов' date_of_birth=datetime.date(2000, 1, 1) email='[e-mail]' address='Москва, ул. Пушкина, д. Колотушкина' enrollment_year=2022 major=<Major.informatics: 'Информатика'> course=3 special_notes=None

Обратите внимание. Мы не передали ключ special_notes, но при этом никаких ошибок не получили. Все дело в том, что в описании этого поля мы передавали default = None.

Старался объяснить работу Pydantic максимально доступно для каждого и надеюсь что к данному моменту вы разобрались что тут и к чему, а значит что мы можем начать внедрять данную модель в FastApi.

Pydantic модель и GET эндпоинт

В GET запросах, при помощи модели, мы указываем какие данные должен получить пользователь. То есть, если пойдет какая-то ошибка в данных на стороне сервера, то пользователь не получит данных, а на бэке можно будет ознакомиться с ошибкой (это мы смоделируем).

Для того чтоб все это работало нам необходимо передать response_model (модель ответа). Передать ее можно двумя разными способами.

@app.get("/student", response_model=SStudent)
def get_student_from_param_id(student_id: int):
    students = json_to_dict_list(path_to_json)
    for student in students:
        if student["student_id"] == student_id:
            return student

В данном случае мы передаем дополнительный аргумент response_model прямо в декоратор. Обратите внимание, я добавил в имя класса дополнительную S. Тем самым я, обычно, описываю что в данном случае речь конкретно про схему (модель).

Второй способ передачи response_model выглядит так:

@app.get("/student")
def get_student_from_param_id(student_id: int) -> SStudent:
    students = json_to_dict_list(path_to_json)
    for student in students:
        if student["student_id"] == student_id:
            return student

В данном синтаксисе мы тоже указываем, что response_model – это SStudent. В работе я чаще использую такой вариант, но вы выбирайте тот что вам более удобен.

Теперь, когда мы передали модель ответа, давайте посмотрим в документацию. Изменилось ли там что либо. Напоминаю, что для запуска необходимо выполнить эту команду из корня проекта:

uvicorn app.main:app --reload  

Заходим в документацию (http://127.0.0.1:8000/docs) и видим:

Мы видим, что благодаря данной модели FastApi построил свой пример ответа. Это очень удобно, не так ли?

Выполним запрос для получения студента с ID = 1 и получим данные:

{
  "student_id": 1,
  "phone_number": "[phone]",
  "first_name": "Иван",
  "last_name": "Иванов",
  "date_of_birth": "1998-05-15",
  "email": "[e-mail]",
  "address": "г. Москва, ул. Пушкина, д. 10, кв. 5",
  "enrollment_year": 2017,
  "major": "Информатика",
  "course": 3,
  "special_notes": "Без особых примет"
}

В JSON (оттуда мы тянем информацию) данные записаны у меня так:

{
  "student_id": 1,
  "first_name": "Иван",
  "last_name": "Иванов",
  "date_of_birth": "1998-05-15",
  "email": "[e-mail]",
  "phone_number": "[phone]",
  "address": "г. Москва, ул. Пушкина, д. 10, кв. 5",
  "enrollment_year": 2017,
  "major": "Информатика",
  "course": 3,
  "special_notes": "Без особых примет"
},

Тут интересно поле с датой рождения. Вы видите, что у меня она записана строкой «1998-05-15», но при этом мы не получили ошибку. Это одна из фишек Pydantic.

Давайте теперь изменим одно из значений у этого пользователя (сделаем не валидным) и посмотрим что у нас получится.

{
  "student_id": 1,
  "first_name": "Иван",
  "last_name": "Иванов",
  "date_of_birth": "1998-05-15",
  "email": "[e-mail]",
  "phone_number": "[phone]",
  "address": "г. Москва, ул. Пушкина, д. 10, кв. 5",
  "enrollment_year": 2040,
  "major": "Информатика",
  "course": 6,
  "special_notes": "Без особых примет"
}

Тут я намеренно допустил 2 ошибки: некорректный год поступления и курс. Проверяем:

Мы видим, что есть ошибка 500, но, при этом, расклада по данной ошибке мы не видим. Это сделано намеренно для безопасности. Так где же ознакомиться с ошибкой сервера?

Смотрим в терминал, где мы выполняли запуск FastApi приложения:

fastapi.exceptions.ResponseValidationError: 1 validation errors:
{'type': 'less_than_equal', 'loc': ('response', 'course'), 'msg': 'Input should be less than or equal to 5', 'input': 6, 'ctx': {'le': 5}}

Мы видим ровно то же описание ошибки, что было при обычном тестировании. Такой ответ позволяет нам сделать несколько выводов:

1. С ошибкой можно будет ознакомиться в логах (пока просто в консоли)

2. Несмотря на количество ошибок в валидации, мы получаем сообщение про 1 ошибку

Думаю с этим все понятно, а как быть с ситуацией когда нам нужно получить информацию по нескольким студентам? К примеру это 10 студентов, а наша модель описывает только одного студента. Все просто!

from typing import Optional, List


@app.get("/students/{course}")
def get_all_students_course(course: int, major: Optional[str] = None, enrollment_year: Optional[int] = 2018) -> List[
    SStudent]:
    students = json_to_dict_list(path_to_json)
    filtered_students = []
    for student in students:
        if student["course"] == course:
            filtered_students.append(student)

    if major:
        filtered_students = [student for student in filtered_students if student['major'].lower() == major.lower()]

    if enrollment_year:
        filtered_students = [student for student in filtered_students if student['enrollment_year'] == enrollment_year]

    return filtered_students

Нам достаточно из модуля typing передать List, а после просто передаем нашу модель. Тем самым мы указываем, что данный метод должен будет вернуть список студентов.

Особо внимательные читатели уже на данном примере видят, что как-то многовато мы передаем аргументов (фильтров), а ведь их может быть десятки (если не верите зайдите в любой интернет-магазин и посмотрите на длину ссылки, когда вы передадите штук 10 фильтров).

(course: int, major: Optional[str] = None, enrollment_year: Optional[int] = 2018)

Конечно, мы можем их все 10, 20 или сколько там будет передавать и описывать, но это как то не по питоновски, правда?

На удивление, для оптимизации официального метода нет, но есть полу-официальный метод. Создателю FastApi задали вопрос о том как обойти проблему с описанием request_body (тела запроса) через отдельный класс и он поделился одной хитростью, которой я поделюсь с вами.

Сейчас мы создадим самый обыкновенный класс, без Pydantic, так как он, к сожалению, не предназначен для формирования тела запроса (request body).

class RBStudent:
    def __init__(self, course: int, major: Optional[str] = None, enrollment_year: Optional[int] = 2018):
        self.course: int = course
        self.major: Optional[str] = major
        self.enrollment_year: Optional[int] = enrollment_year

Теперь нам необходимо этот класс передать в наш эндпоинт. Тут тоже будет хитрость.

@app.get("/students/{course}")
def get_all_students_course(request_body: RBStudent) -> List[SStudent]:
    students = json_to_dict_list(path_to_json)
    filtered_students = []
    for student in students:
        if student["course"] == request_body.course:
            filtered_students.append(student)

    if request_body.major:
        filtered_students = [student for student in filtered_students if
                             student['major'].lower() == request_body.major.lower()]

    if request_body.enrollment_year:
        filtered_students = [student for student in filtered_students if
                             student['enrollment_year'] == request_body.enrollment_year]

    return filtered_students

В таком виде, к сожалению, код работать не будет, а мы получим такую ошибку:

fastapi.exceptions.FastAPIError: Invalid args for response field! Hint: check that <class 'app.main.RBStudent'> is a valid Pydantic field type. If you are using a return type an

notation that is not a valid Pydantic field (e.g. Union[Response, dict, None]) you can disable generating the response model from the type annotation with the path operation decorator parameter response_model=None. 

Ничего. Сейчас мы это исправим.

Для того чтоб решить данную проблему нам необходимо воспользоваться функцией Depends. Импортируем ее из FastApi:

from fastapi import FastAPI, Depends

Данная функцию мы будем подробно рассматривать в других статьях, пока просто импортируем.

Изменяем функцию:

@app.get("/students/{course}")
def get_all_students_course(request_body: RBStudent = Depends()) -> List[SStudent]:
    students = json_to_dict_list(path_to_json)
    filtered_students = []
    for student in students:
        if student["course"] == request_body.course:
            filtered_students.append(student)

    if request_body.major:
        filtered_students = [student for student in filtered_students if
                             student['major'].lower() == request_body.major.lower()]

    if request_body.enrollment_year:
        filtered_students = [student for student in filtered_students if
                             student['enrollment_year'] == request_body.enrollment_year]

    return filtered_students

FastApi больше не ругается и мы можем воспользоваться данной функцией в документации (как раз посмотрим как FastApi опишет корректный ответ).

Видим, что все корректно отработало, но, при этом, мы сильно очистили свой код.

Надеюсь, что к данному моменту вы полностью закрепили тему с Pydantic и описанием модели запроса, а это значит, что можно переходить к POST, PUT и DELETE методам.

Небольшая подготовка.

Далее я буду выполнять демонстрацию работы POST, PUT и DELETE методов на примере библиотеки json_db_lite. Вам ее использовать не обязательно. Основная суть в том, что мы превращаем стандартный JSON в некое подобие мини-базы данных. В следующих же статьях мы будем говорить про интеграцию и работу SQLAlchemi.

pip install --upgrade json_db_lite

POST методы в FastApi

Напоминаю, что смысл POST методов в том, чтоб отправить данные от клиента в сервер (базу данных) и, как по мне, лучшим тут примером будет добавление нового студента в базу данных.

Для начала напишем функции, которые позволят нам имитировать работу с базой данных:

from json_db_lite import JSONDatabase

# инициализация объекта
small_db = JSONDatabase(file_path='students.json')


# получаем все записи
def json_to_dict_list():
    return small_db.get_all_records()


# добавляем студента
def add_student(student: dict):
    student['date_of_birth'] = student['date_of_birth'].strftime('%Y-%m-%d')
    small_db.add_records(student)
    return True


# обновляем данные по студенту
def upd_student(upd_filter: dict, new_data: dict):
    small_db.update_record_by_key(upd_filter, new_data)
    return True


# удаляем студента
def dell_student(key: str, value: str):
    small_db.delete_record_by_key(key, value)
    return True

Функции будут выглядеть так, а подробное описание каждого метода этой библиотеки вы найдете в статье «Новая библиотека для работы с JSON: json_db_lite».

Теперь правильно напишем POST запрос, который будет принимать данные о студенте для добавления, после будет выполнять проверку их валидности, а затем, если все данные валидные, мы будем добавлять новое значение в нашу мини базу данных (add_student).

@app.post("/add_student")
def add_student_handler(student: SStudent):
    student_dict = student.dict()
    check = add_student(student_dict)
    if check:
        return {"message": "Студент успешно добавлен!"}
    else:
        return {"message": "Ошибка при добавлении студента"}

Зайдем в документацию и посмотрим что у нас получилось:

Вы видите, что полей для ввода данных у нас больше нет, но, при этом, FastApi нам подсказывает как должны выглядеть данные для добавления. Давайте их и попробуем добавить.

{

  "detail": [

    {

      "type": "value_error",

      "loc": [

        "body",

        "phone_number"

      ],

      "msg": "Value error, Номер телефона должен начинаться с \"+\" и содержать от 1 до 15 цифр",

      "input": "string",

      "ctx": {

        "error": {}

      }

    },

    {

      "type": "value_error",

      "loc": [

        "body",

        "date_of_birth"

      ],

      "msg": "Value error, Дата рождения должна быть в прошлом",

      "input": "2024-07-07",

      "ctx": {

        "error": {}

      }

    },

    {

      "type": "greater_than_equal",

      "loc": [

        "body",

        "enrollment_year"

      ],

      "msg": "Input should be greater than or equal to 2002",

      "input": 0,

      "ctx": {

        "ge": 2002

      }

    },

    {

      "type": "greater_than_equal",

      "loc": [

        "body",

        "course"

      ],

      "msg": "Input should be greater than or equal to 1",

      "input": 0,

      "ctx": {

        "ge": 1

      }

    }

  ]

}

И вот мы получили столько ошибок. Обратите внимание, что в данном случае мы видим ошибки явно, а не через бэкенд, как в случае с ошибками при ошибках валидации на GET запросах.

Ошибки все те-же. Давайте исправим и повторим запрос:

Корректное тело запроса

Результат

Мы видим, что студент успешно добавлен, а мы не получили никаких ошибок.

На практике, конечно, данные не добавляются в JSON после POST запроса, но текущего примера, как по мне, будет более чем достаточно чтоб объяснить вам общий принцип обработки POST запросов в FastApi.

Теперь рассмотрим PUT и DELETE методы.

Обработка PUT методов в FastAPI

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

def upd_student(upd_filter: dict, new_data: dict):
    small_db.update_record_by_key(upd_filter, new_data)
    return True

Следовательно, тут у нас будет одна модель для фильтрации, а вторая модель с новыми данными для студента. Опишем обе модели.

class SUpdateFilter(BaseModel):
    student_id: int


# Определение модели для новых данных студента
class SStudentUpdate(BaseModel):
    course: int = Field(..., ge=1, le=5, description="Курс должен быть в диапазоне от 1 до 5")
    major: Optional[Major] = Field(..., description="Специальность студента")

Метод будет выглядеть так:

@app.put("/update_student")
def update_student_handler(filter_student: SUpdateFilter, new_data: SStudentUpdate):
    check = upd_student(filter_student.dict(), new_data.dict())
    if check:
        return {"message": "Информация о студенте успешно обновлена!"}
    else:
        raise HTTPException(status_code=400, detail="Ошибка при обновлении информации о студенте")

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

Данный метод будет обновлять данные по конкретному студенту, принимая его ID. В новых данных мы должны будем передать курс и специальность студента. К данному моменту вопросов к синтаксису у вас уже не должно быть.

Смотрим.

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

Передадим данные и попробуем выполнить обновление.

{

  "filter_student": {

    "student_id": 12

  },

  "new_data": {

    "course": 5,

    "major": "Экономика"

  }

}

Отлично и на последок посмотрим на DELETE запрос.

Для начала напишем модель под функцию

def dell_student(key: str, value: str):
    small_db.delete_record_by_key(key, value)
    return True

Вот пример модели:

class SDeleteFilter(BaseModel):
    key: str
    value: Any

Так как значение ключа может быть любым, я в качестве описания указал Any (не забудьте импортировать с typing).

Пример функции для удаления студента:

@app.delete("/delete_student")
def delete_student_handler(filter_student: SDeleteFilter):
    check = dell_student(filter_student.key, filter_student.value)
    if check:
        return {"message": "Студент успешно удален!"}
    else:
        raise HTTPException(status_code=400, detail="Ошибка при удалении студента")

В данном и предыдущем примере я использовал HTTPException. Пока это просто демонстрация, а так, теме исключений и их обработке я посвящу отдельную статью.

Давайте посмотрим на то, как выглядит метод для удаления студента:

Выполняю запрос:

{"key": "student_id", "value": 12}

Результат:

Заключение

Друзья, теперь вы знаете:

• Как обрабатывать GET, POST, DELETE и PUT запросы в FastAPI.

• Что такое модели в FastAPI и, в частности, модели Pydantic.

• Если не просто читали, а писали код вместе со мной, то вы на практике закрепили и методы и работу с моделями

Как и в прошлый раз, ваша поддержка в виде лайков, подписок и комментариев даст мне понять, что стоит продолжать создавать такой объемный контент, на который всегда не хватает времени.

Эти навыки дадут вам достаточную основу для более глубоких тем, таких как: асинхронная работа, интеграция с базой данных SQLite, фоновые задачи, самописная авторизация и многое другое.

Исходники кода из этой публикации, а также эксклюзивный контент, вы найдете в моем телеграмм-канале «Легкий путь в Python».

Всего доброго!