RESTful API — Полное руководство

from flask import Flask, jsonify, request, abort
from datetime import datetime

app = Flask(__name__)

# ═══════════════════════════════════════════════════════════════
#                    ПРОСТАЯ "БАЗА ДАННЫХ"
# ═══════════════════════════════════════════════════════════════

# В реальном проекте это будет PostgreSQL, MongoDB и т.д.
books_db = {
    1: {
        "id": 1,
        "title": "Война и мир",
        "author": "Лев Толстой",
        "year": 1869,
        "created_at": "2024-01-01T10:00:00Z"
    },
    2: {
        "id": 2,
        "title": "Преступление и наказание",
        "author": "Фёдор Достоевский",
        "year": 1866,
        "created_at": "2024-01-02T12:00:00Z"
    }
}
next_id = 3

# ═══════════════════════════════════════════════════════════════
#                     ВСПОМОГАТЕЛЬНЫЕ ФУНКЦИИ
# ═══════════════════════════════════════════════════════════════

def success_response(data, status_code=200):
    """Формирует успешный ответ"""
    return jsonify({
        "status": "success",
        "data": data
    }), status_code

def error_response(message, status_code, errors=None):
    """Формирует ответ с ошибкой"""
    response = {
        "status": "error",
        "message": message
    }
    if errors:
        response["errors"] = errors
    return jsonify(response), status_code

def validate_book(data, partial=False):
    """Валидация данных книги"""
    errors = []

    if not partial:
        if not data.get("title"):
            errors.append({"field": "title", "message": "Title is required"})
        if not data.get("author"):
            errors.append({"field": "author", "message": "Author is required"})

    if "year" in data:
        if not isinstance(data["year"], int) or data["year"] < 0:
            errors.append({"field": "year", "message": "Year must be a positive integer"})

    return errors

# ═══════════════════════════════════════════════════════════════
#                        REST ENDPOINTS
# ═══════════════════════════════════════════════════════════════

# ─────────────── GET /books — Получить все книги ───────────────
@app.route('/api/v1/books', methods=['GET'])
def get_books():
    """
    Получить список всех книг

    Query параметры:
        - author: фильтр по автору
        - year: фильтр по году
        - sort: сортировка (title, -title, year, -year)
    """
    books = list(books_db.values())

    # Фильтрация
    author = request.args.get('author')
    if author:
        books = [b for b in books if author.lower() in b['author'].lower()]

    year = request.args.get('year', type=int)
    if year:
        books = [b for b in books if b['year'] == year]

    # Сортировка
    sort = request.args.get('sort', 'id')
    reverse = sort.startswith('-')
    sort_field = sort.lstrip('-')
    if sort_field in ['id', 'title', 'year']:
        books = sorted(books, key=lambda x: x.get(sort_field, ''), reverse=reverse)

    return success_response(books)

# ─────────────── GET /books/:id — Получить одну книгу ───────────────
@app.route('/api/v1/books/<int:book_id>', methods=['GET'])
def get_book(book_id):
    """Получить книгу по ID"""
    book = books_db.get(book_id)

    if not book:
        return error_response(f"Book with id {book_id} not found", 404)

    return success_response(book)

# ─────────────── POST /books — Создать книгу ───────────────
@app.route('/api/v1/books', methods=['POST'])
def create_book():
    """Создать новую книгу"""
    global next_id

    # Проверяем Content-Type
    if not request.is_json:
        return error_response("Content-Type must be application/json", 415)

    data = request.get_json()

    # Валидация
    errors = validate_book(data)
    if errors:
        return error_response("Validation failed", 422, errors)

    # Создаём книгу
    book = {
        "id": next_id,
        "title": data["title"],
        "author": data["author"],
        "year": data.get("year"),
        "created_at": datetime.utcnow().isoformat() + "Z"
    }

    books_db[next_id] = book
    next_id += 1

    return success_response(book, 201)

# ─────────────── PUT /books/:id — Полное обновление ───────────────
@app.route('/api/v1/books/<int:book_id>', methods=['PUT'])
def update_book(book_id):
    """Полностью заменить книгу"""
    if book_id not in books_db:
        return error_response(f"Book with id {book_id} not found", 404)

    if not request.is_json:
        return error_response("Content-Type must be application/json", 415)

    data = request.get_json()

    # Валидация (все поля обязательны для PUT)
    errors = validate_book(data, partial=False)
    if errors:
        return error_response("Validation failed", 422, errors)

    # Обновляем (полная замена, но сохраняем id и created_at)
    old_book = books_db[book_id]
    books_db[book_id] = {
        "id": book_id,
        "title": data["title"],
        "author": data["author"],
        "year": data.get("year"),
        "created_at": old_book["created_at"],
        "updated_at": datetime.utcnow().isoformat() + "Z"
    }

    return success_response(books_db[book_id])

# ─────────────── PATCH /books/:id — Частичное обновление ───────────────
@app.route('/api/v1/books/<int:book_id>', methods=['PATCH'])
def patch_book(book_id):
    """Частично обновить книгу"""
    if book_id not in books_db:
        return error_response(f"Book with id {book_id} not found", 404)

    if not request.is_json:
        return error_response("Content-Type must be application/json", 415)

    data = request.get_json()

    # Валидация (частичная)
    errors = validate_book(data, partial=True)
    if errors:
        return error_response("Validation failed", 422, errors)

    # Обновляем только переданные поля
    book = books_db[book_id]
    for field in ['title', 'author', 'year']:
        if field in data:
            book[field] = data[field]

    book["updated_at"] = datetime.utcnow().isoformat() + "Z"

    return success_response(book)

# ─────────────── DELETE /books/:id — Удалить книгу ───────────────
@app.route('/api/v1/books/<int:book_id>', methods=['DELETE'])
def delete_book(book_id):
    """Удалить книгу"""
    if book_id not in books_db:
        return error_response(f"Book with id {book_id} not found", 404)

    del books_db[book_id]

    # 204 No Content — стандарт для успешного DELETE
    return '', 204

# ═══════════════════════════════════════════════════════════════
#                     ОБРАБОТКА ОШИБОК
# ═══════════════════════════════════════════════════════════════

@app.errorhandler(404)
def not_found(error):
    return error_response("Resource not found", 404)

@app.errorhandler(500)
def internal_error(error):
    return error_response("Internal server error", 500)

# ═══════════════════════════════════════════════════════════════
#                          ЗАПУСК
# ═══════════════════════════════════════════════════════════════

if __name__ == '__main__':
    app.run(debug=True, port=5000)

from fastapi import FastAPI, HTTPException, Query
from pydantic import BaseModel, Field
from typing import Optional, List
from datetime import datetime
from enum import Enum

app = FastAPI(
    title="Books API",
    description="REST API для управления книгами",
    version="1.0.0"
)

# ═══════════════════════════════════════════════════════════════
#                    PYDANTIC МОДЕЛИ (СХЕМЫ)
# ═══════════════════════════════════════════════════════════════

class BookBase(BaseModel):
    """Базовые поля книги"""
    title: str = Field(..., min_length=1, max_length=200, example="Война и мир")
    author: str = Field(..., min_length=1, max_length=100, example="Лев Толстой")
    year: Optional[int] = Field(None, ge=0, le=2100, example=1869)

class BookCreate(BookBase):
    """Схема для создания книги"""
    pass

class BookUpdate(BaseModel):
    """Схема для частичного обновления"""
    title: Optional[str] = Field(None, min_length=1, max_length=200)
    author: Optional[str] = Field(None, min_length=1, max_length=100)
    year: Optional[int] = Field(None, ge=0, le=2100)

class BookResponse(BookBase):
    """Схема ответа с книгой"""
    id: int
    created_at: datetime
    updated_at: Optional[datetime] = None

    class Config:
        from_attributes = True

class SortOrder(str, Enum):
    """Порядок сортировки"""
    asc = "asc"
    desc = "desc"

# ═══════════════════════════════════════════════════════════════
#                    ПРОСТАЯ "БАЗА ДАННЫХ"
# ═══════════════════════════════════════════════════════════════

books_db: dict[int, dict] = {
    1: {
        "id": 1,
        "title": "Война и мир",
        "author": "Лев Толстой",
        "year": 1869,
        "created_at": datetime(2024, 1, 1, 10, 0),
        "updated_at": None
    },
    2: {
        "id": 2,
        "title": "Преступление и наказание",
        "author": "Фёдор Достоевский",
        "year": 1866,
        "created_at": datetime(2024, 1, 2, 12, 0),
        "updated_at": None
    }
}
next_id = 3

# ═══════════════════════════════════════════════════════════════
#                        REST ENDPOINTS
# ═══════════════════════════════════════════════════════════════

@app.get("/api/v1/books", response_model=List[BookResponse], tags=["Books"])
async def get_books(
    author: Optional[str] = Query(None, description="Фильтр по автору"),
    year: Optional[int] = Query(None, description="Фильтр по году"),
    sort_by: str = Query("id", enum=["id", "title", "year"]),
    order: SortOrder = Query(SortOrder.asc)
):
    """Получить список всех книг с фильтрацией и сортировкой"""
    books = list(books_db.values())

    # Фильтрация
    if author:
        books = [b for b in books if author.lower() in b["author"].lower()]
    if year:
        books = [b for b in books if b["year"] == year]

    # Сортировка
    reverse = order == SortOrder.desc
    books = sorted(books, key=lambda x: x.get(sort_by) or "", reverse=reverse)

    return books

@app.get("/api/v1/books/{book_id}", response_model=BookResponse, tags=["Books"])
async def get_book(book_id: int):
    """Получить книгу по ID"""
    if book_id not in books_db:
        raise HTTPException(status_code=404, detail=f"Book {book_id} not found")
    return books_db[book_id]

@app.post("/api/v1/books", response_model=BookResponse, status_code=201, tags=["Books"])
async def create_book(book: BookCreate):
    """Создать новую книгу"""
    global next_id

    new_book = {
        "id": next_id,
        **book.model_dump(),
        "created_at": datetime.utcnow(),
        "updated_at": None
    }

    books_db[next_id] = new_book
    next_id += 1

    return new_book

@app.put("/api/v1/books/{book_id}", response_model=BookResponse, tags=["Books"])
async def update_book(book_id: int, book: BookCreate):
    """Полностью обновить книгу"""
    if book_id not in books_db:
        raise HTTPException(status_code=404, detail=f"Book {book_id} not found")

    old_book = books_db[book_id]
    books_db[book_id] = {
        "id": book_id,
        **book.model_dump(),
        "created_at": old_book["created_at"],
        "updated_at": datetime.utcnow()
    }

    return books_db[book_id]

@app.patch("/api/v1/books/{book_id}", response_model=BookResponse, tags=["Books"])
async def patch_book(book_id: int, book: BookUpdate):
    """Частично обновить книгу"""
    if book_id not in books_db:
        raise HTTPException(status_code=404, detail=f"Book {book_id} not found")

    # Обновляем только переданные поля
    update_data = book.model_dump(exclude_unset=True)
    for field, value in update_data.items():
        books_db[book_id][field] = value

    books_db[book_id]["updated_at"] = datetime.utcnow()

    return books_db[book_id]

@app.delete("/api/v1/books/{book_id}", status_code=204, tags=["Books"])
async def delete_book(book_id: int):
    """Удалить книгу"""
    if book_id not in books_db:
        raise HTTPException(status_code=404, detail=f"Book {book_id} not found")

    del books_db[book_id]
    return None

# ═══════════════════════════════════════════════════════════════
#                         HEALTH CHECK
# ═══════════════════════════════════════════════════════════════

@app.get("/health", tags=["System"])
async def health_check():
    """Проверка работоспособности API"""
    return {"status": "healthy", "timestamp": datetime.utcnow()}