Какая функция считается RESTful?

Что такое RESTful функция?

Вопрос подразумевает концепцию REST (Representational State Transfer) при проектировании веб-приложений. Это архитектурный стиль для веб-сервисов, где API следует определённым принципам.

1. Основные принципы REST

# REST — это стиль архитектуры, основанный на HTTP методах
# Ключевые принципы:

# 1. Ресурсы (Resources) — существительные
GET    /users          # получить всех пользователей
GET    /users/123      # получить пользователя с ID 123
POST   /users          # создать нового пользователя
PUT    /users/123      # заменить пользователя (полное обновление)
PATCH  /users/123      # частичное обновление
DELETE /users/123      # удалить пользователя

# ❌ Неправильно (глаголы в URL)
GET    /getUser/123
GET    /createUser
GET    /deleteUser/123

2. Правильные RESTful endpoint'ы

# ✅ RESTful подход

# Коллекции (множественное число)
GET    /api/v1/users              # список всех
POST   /api/v1/users              # создание нового

# Конкретный ресурс
GET    /api/v1/users/123           # получить конкретного
PUT    /api/v1/users/123           # заменить
PATCH  /api/v1/users/123           # обновить
DELETE /api/v1/users/123           # удалить

# Вложенные ресурсы
GET    /api/v1/users/123/posts     # посты пользователя 123
GET    /api/v1/users/123/posts/45  # конкретный пост
POST   /api/v1/users/123/posts     # создать пост для пользователя

# Операции над ресурсом (редко, но иногда нужны)
POST   /api/v1/users/123/avatar    # загрузить аватар
POST   /api/v1/comments/123/like   # лайк комментария

3. RESTful контроллер в FastAPI

from fastapi import APIRouter, HTTPException, status
from pydantic import BaseModel
from typing import List

router = APIRouter(prefix="/api/v1/users", tags=["users"])

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

class UserCreate(BaseModel):
    name: str
    email: str

@router.get("")
async def list_users() -> List[User]:
    """Получить список всех пользователей"""
    return []

@router.get("/{user_id}")
async def get_user(user_id: int) -> User:
    """Получить конкретного пользователя"""
    raise HTTPException(status_code=404, detail="Not found")

@router.post("", status_code=201)
async def create_user(user: UserCreate) -> User:
    """Создать нового пользователя"""
    pass

@router.put("/{user_id}")
async def update_user(user_id: int, user: UserCreate) -> User:
    """Полное обновление пользователя"""
    pass

@router.patch("/{user_id}")
async def partial_update_user(user_id: int, user: dict) -> User:
    """Частичное обновление"""
    pass

@router.delete("/{user_id}", status_code=204)
async def delete_user(user_id: int):
    """Удалить пользователя"""
    pass

4. Правильные HTTP методы

• GET — получение данных (safe и idempotent)
• POST — создание нового ресурса (не idempotent)
• PUT — полное обновление ресурса (idempotent)
• PATCH — частичное обновление (может быть не idempotent)
• DELETE — удаление ресурса (idempotent)
• HEAD — GET без тела ответа
• OPTIONS — информация о доступных методах

5. Правильные статус коды

200  OK              — успех
201  Created         — ресурс создан (POST)
202  Accepted        — принято, обработка в процессе
204  No Content      — успех, без тела (DELETE)
400  Bad Request     — ошибка валидации
401  Unauthorized    — не авторизован
403  Forbidden       — нет доступа
404  Not Found       — ресурс не найден
409  Conflict        — конфликт
500  Server Error    — ошибка сервера

6. Что НЕ является RESTful

# ❌ Неправильные примеры

# Глаголы в URL
GET  /api/getUser/123
GET  /api/createUser
GET  /api/deleteUser/123

# Неправильные HTTP методы
GET  /api/users/123/delete  # используй DELETE!
GET  /api/users/create      # используй POST!

# Случайная структура
GET  /get_users
POST /create_post
GET  /my/data/structure

7. Фильтрация, сортировка, пагинация

# ✅ Query параметры
GET  /api/v1/users?page=1&limit=10           # пагинация
GET  /api/v1/users?sort=name&order=asc       # сортировка
GET  /api/v1/users?status=active&role=admin  # фильтрация
GET  /api/v1/users?q=john                    # поиск

8. API Versioning

# ✅ Правильное вверсионирование
GET  /api/v1/users      # версия 1
GET  /api/v2/users      # версия 2
GET  /api/v3/users      # версия 3

Итоги

RESTful функция/контроллер должна:

• Использовать существительные в URL (не глаголы)
• Использовать правильные HTTP методы
• Возвращать правильные статус коды
• Работать с ресурсами как с сущностями
• Быть stateless (не держать состояние)
• Версионировать API
• Поддерживать фильтрацию, сортировку, пагинацию

Главное правило: REST — это архитектурный стиль, где каждый URL это ресурс, а HTTP методы это операции над ними