API Эндпоинты

В этом разделе представлена документация по всем API эндпоинтам, доступным в backend части Boilerplate. Здесь вы найдете информацию о том, как использовать и настраивать эти эндпоинты.

Обзор API

Backend часть Boilerplate построена на FastAPI, что обеспечивает высокую производительность и удобство разработки. Все API эндпоинты автоматически документируются с помощью Swagger UI и ReDoc.

Доступ к API документации:

Структура API

API эндпоинты организованы в роутеры по функциональным областям. Основная структура API:

  • /api/v1/auth → Аутентификация и авторизация
  • /api/v1/users → Управление пользователями
  • /api/v1/items → Управление элементами
  • /api/v1/health → Проверка работоспособности API

Примеры API запросов

Аутентификация

Пример запроса для получения токена доступа:

bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=user@example.com&password=password123'

Пример ответа:

json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Получение данных пользователя

Пример запроса для получения данных текущего пользователя:

bash
curl -X GET http://localhost:8000/api/v1/users/me \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Пример ответа:

json
{
  "id": 1,
  "email": "user@example.com",
  "full_name": "Test User",
  "is_active": true,
  "is_superuser": false
}

Создание новых эндпоинтов

Для создания нового API эндпоинта, следуйте этим шагам:

  1. Создайте или выберите подходящий роутер в директории backend/app/api/routes

  2. Определите новый эндпоинт с использованием декораторов FastAPI:

    python
    from typing import List
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession

from app.api.deps import get_current_user, get_db
from app.models.user import User
from app.schemas.item import ItemCreate, ItemResponse

router = APIRouter()

@router.post("/", response_model=ItemResponse, status_code=status.HTTP_201_CREATED)
async def create_item(
    item_in: ItemCreate,
    db: AsyncSession = Depends(get_db),
    current_user: User = Depends(get_current_user)
):
    """
    Создание нового элемента.
    """
    # Ваша бизнес-логика здесь
    
    return new_item

  3. Добавьте роутер в приложение в файле backend/app/api/api.py:

    python
    from fastapi import APIRouter

from app.api.routes import auth, users, items

api_router = APIRouter()
api_router.include_router(auth.router, prefix="/auth", tags=["auth"])
api_router.include_router(users.router, prefix="/users", tags=["users"])
api_router.include_router(items.router, prefix="/items", tags=["items"])

Лучшие практики

  • Всегда определяйте модели запросов и ответов с помощью Pydantic
  • Используйте правильные HTTP методы (GET, POST, PUT, DELETE)
  • Всегда добавляйте документацию к эндпоинтам
  • Обрабатывайте ошибки с помощью правильных HTTP статус-кодов
  • Используйте middleware для логирования и обработки ошибок