REST API: принципы проектирования и современная реализация (Python 3.12+)

REST API — это контракт между системами, а не просто набор эндпоинтов. Его качество напрямую влияет на масштабируемость, тестируемость и стоимость разработки.

Сегодня REST уже редко существует “в чистом виде” — почти всегда он дополняется:

строгой типизацией
контрактами (OpenAPI)
валидацией (Pydantic)
асинхронностью
слоистой архитектурой (Clean Architecture / Hexagonal)

1. Что такое REST в инженерном смысле

REST (Representational State Transfer) — архитектурный стиль, основанный на:

ресурсах (users, orders, payments)
стандартных HTTP-методах
отсутствии состояния (stateless)
единых интерфейсах доступа

Ключевая идея

URL = ресурс, HTTP-метод = действие

Пример:

GET /users — получить список
GET /users/{id} — получить пользователя
POST /users — создать
PATCH /users/{id} — обновить
DELETE /users/{id} — удалить

2. Современные принципы проектирования API

2.1 SOLID в контексте API

Да, SOLID применим не только к классам:

S (Single Responsibility) — один endpoint = одна ответственность
O (Open/Closed) — расширяем через новые endpoints, а не ломаем старые
L (Liskov) — одинаковые ресурсы ведут себя одинаково
I (Interface Segregation) — не перегружать ответы лишними полями
D (Dependency Inversion) — бизнес-логика не зависит от HTTP слоя

2.2 Чистая архитектура API

Рекомендуемая структура:

2.3 Типизация (Python 3.12+)

Современный Python = строгая типизация:

Плюс:

mypy / pyright
IDE автодополнение
меньше runtime ошибок

2.4 Контракт API (OpenAPI)

Сейчас API без OpenAPI — почти “не прод”.

FastAPI генерирует его автоматически:

Swagger UI
ReDoc
machine-readable schema

3. Лучшие практики проектирования

3.1 Ресурсы, а не действия

❌ плохо:

✔ правильно:

3.2 HTTP-коды — как язык API

200 — OK
201 — Created
204 — No Content
400 — Validation error
401 — Unauthorized
403 — Forbidden
404 — Not found
500 — Server error

3.3 Единый формат ошибок

3.4 Пагинация и фильтры

Важно:

limit всегда ограничен
сортировка через whitelist полей

3.5 Версионирование API

Лучший вариант:

Альтернатива (реже используется):

headers versioning

3.6 Безопасность

Минимальный набор:

HTTPS всегда
JWT / OAuth2
rate limiting
input validation
CORS policy

4. Современный пример: FastAPI + Python 3.12

Flask уже устаревший для новых API (он sync и менее строгий).

Установка:

Реализация

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class UserCreate(BaseModel):
    name: str

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

db: list[User] = [
    User(id=1, name="Alice"),
    User(id=2, name="Bob")
]

@app.get("/users", response_model=list[User])
def get_users():
    return db


@app.get("/users/{user_id}", response_model=User)
def get_user(user_id: int):
    user = next((u for u in db if u.id == user_id), None)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user


@app.post("/users", response_model=User, status_code=201)
def create_user(payload: UserCreate):
    new_user = User(id=len(db) + 1, name=payload.name)
    db.append(new_user)
    return new_user

5. Что здесь важно (по делу)

Что улучшилось по сравнению с “классикой”:

строгие типы (Pydantic)
автодокументация API
единый контракт ответа
отсутствие ручного JSON
явные схемы данных
проще тестировать

6. Архитектурный уровень выше (то, к чему стоит идти)

Если хочешь делать “взрослые” API:

FastAPI + PostgreSQL
SQLAlchemy 2.0 async
Redis (кэш / rate limit)
Celery / RQ (фоновые задачи)
OpenTelemetry (трассировка)
Docker + CI/CD
API Gateway (на масштабе)

7. Итог

REST сегодня — это не просто CRUD.

Это:

контракт
архитектура
типизация
документация
безопасность
масштабирование

Если API сделан плохо — система разваливается не сразу, но неизбежно. И обычно в самый неудобный момент.