Conceptos Clave de FastAPI

FastAPI es un framework web de Python moderno y rápido (de alto rendimiento) para construir APIs. Está basado en las anotaciones de tipo estándar de Python y está construido con Starlette y Pydantic.

Características Principales

  1. Alto Rendimiento: comparable con NodeJS y Go, es uno de los frameworks de Python más rápidos
  2. Desarrollo Rápido: velocidad de desarrollo aproximadamente 200%-300% mayor
  3. Menos Errores: reduce aproximadamente un 40% de errores humanos
  4. Intuitivo: potente soporte de editores, autocompletado en todas partes
  5. Sencillo: fácil de usar y aprender, reduce el tiempo de lectura de documentación

ASGI y Programación Asíncrona

¿Qué es ASGI?

ASGI (Interfaz de Puerta de Enlace de Servidor Asíncrono) es la interfaz estándar entre los servidores web asíncronos de Python y las aplicaciones.

Comparación WSGI vs ASGI:

Ejemplo

# Aplicación WSGI (síncrona) - estilo Flask tradicional
def wsgi_app(environ, start_response):
    status = '200 OK'
    response_headers = [('Content-type', 'text/plain')]
    start_response(status, response_headers)
    return [b'Hello World']

# Aplicación ASGI (asíncrona) - estilo FastAPI
async def asgi_app(scope, receive, send):
    await send({
        'type': 'http.response.start',
        'status': 200,
        'headers': [(b'content-type', b'text/plain')],
    })
    await send({
        'type': 'http.response.body',
        'body': b'Hello World',
    })

Conceptos Clave de la Programación Asíncrona

Ejecución Síncrona vs Asíncrona:

Ejemplo

import asyncio
import time
import httpx

# Modo síncrono - ejecución bloqueante
def sync_fetch_data():
    start_time = time.time()
    # Simular tres solicitudes de red
    time.sleep(1)  # Primera solicitud
    time.sleep(1)  # Segunda solicitud
    time.sleep(1)  # Tercera solicitud
    print(f"Tiempo de ejecución síncrono: {time.time() - start_time:.2f} segundos")  # Aproximadamente 3 segundos

# Modo asíncrono - ejecución concurrente
async def async_fetch_data():
    start_time = time.time()
    # Las tres solicitudes se ejecutan concurrentemente
    await asyncio.gather(
        asyncio.sleep(1),  # Primera solicitud
        asyncio.sleep(1),  # Segunda solicitud
        asyncio.sleep(1),  # Tercera solicitud
    )
    print(f"Tiempo de ejecución asíncrono: {time.time() - start_time:.2f} segundos")  # Aproximadamente 1 segundo

# Ejecutar ejemplo
sync_fetch_data()  # Salida: Tiempo de ejecución síncrono: 3.00 segundos
asyncio.run(async_fetch_data())  # Salida: Tiempo de ejecución asíncrono: 1.00 segundos

Operaciones de Ruta Asíncronas en FastAPI:

Ejemplo

from fastapi import FastAPI
import asyncio

app = FastAPI()

# Operación de ruta síncrona
@app.get("/sync")
def sync_endpoint():
    # Las operaciones síncronas bloquean toda la aplicación
    time.sleep(2)
    return {"message": "Respuesta síncrona"}

# Operación de ruta asíncrona (recomendada)
@app.get("/async")
async def async_endpoint():
    # Las operaciones asíncronas no bloquean otras solicitudes
    await asyncio.sleep(2)
    return {"message": "Respuesta asíncrona"}

# Ejemplo de operación de base de datos asíncrona
@app.get("/users/{user_id}")
async def get_user(user_id: int):
    # Consulta asíncrona a la base de datos
    user = await database.fetch_one(
        "SELECT * FROM users WHERE id = :user_id",
        {"user_id": user_id}
    )
    return user

¿Cuándo Usar Asincronía?

Escenarios adecuados para asincronía:

  • Operaciones de base de datos
  • Solicitudes de red (llamadas a API)
  • Operaciones de E/S de archivos
  • Operaciones con largas esperas

Escenarios no adecuados para asincronía:

  • Cómputo intensivo en CPU
  • Procesamiento de datos simple
  • Operaciones sin espera de E/S

Ejemplo

# Buen uso de asincronía
@app.get("/weather")
async def get_weather():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.weather.com/data")
        return response.json()

# Asincronía innecesaria (sin espera de E/S)
@app.get("/calculate")
def calculate_sync():  # Es suficiente mantenerlo síncrono
    result = sum(range(1000000))
    return {"result": result}

Principios de Diseño de API REST

Conceptos Básicos de REST

REST (Transferencia de Estado Representacional) es un estilo de diseño de API web que enfatiza:

  • Orientación a recursos: la URL representa el recurso
  • Sin estado: cada solicitud es independiente
  • Interfaz uniforme: utiliza métodos HTTP estándar
  • Sistema en capas: admite almacenamiento en caché, balanceo de carga, etc.

Diseño de URL RESTful

Ejemplo de buen diseño de URL:

Ejemplo

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel
from typing import List, Optional

app = FastAPI()

# Colección de recursos y recurso individual
@app.get("/users")  # GET /users - Obtener lista de usuarios
async def get_users():
    return users_db

@app.get("/users/{user_id}")  # GET /users/123 - Obtener un usuario específico
async def get_user(user_id: int):
    return find_user(user_id)

@app.post("/users")  # POST /users - Crear un nuevo usuario
async def create_user(user: UserCreate):
    return create_new_user(user)

@app.put("/users/{user_id}")  # PUT /users/123 - Actualizar completamente un usuario
async def update_user(user_id: int, user: UserUpdate):
    return update_existing_user(user_id, user)

@app.patch("/users/{user_id}")  # PATCH /users/123 - Actualizar parcialmente un usuario
async def patch_user(user_id: int, user: UserPatch):
    return patch_existing_user(user_id, user)

@app.delete("/users/{user_id}")  # DELETE /users/123 - Eliminar un usuario
async def delete_user(user_id: int):
    return delete_existing_user(user_id)

# Recursos anidados
@app.get("/users/{user_id}/posts")  # Obtener todos los artículos de un usuario
async def get_user_posts(user_id: int):
    return get_posts_by_user(user_id)

@app.post("/users/{user_id}/posts")  # Crear un nuevo artículo para un usuario
async def create_user_post(user_id: int, post: PostCreate):
    return create_post_for_user(user_id, post)

Principios de Diseño de URL:

好的设计
GET    /api/v1/users              # 获取用户列表
GET    /api/v1/users/123          # 获取用户 123
POST   /api/v1/users              # 创建用户
GET    /api/v1/users/123/orders   # 获取用户 123 的订单

# 不好的设计
GET    /api/v1/getAllUsers        # 动词不应该在 URL 中
GET    /api/v1/user/123           # 集合名应该用复数
POST   /api/v1/createUser         # URL 中包含动作
GET    /api/v1/users-orders-123   # 关系不清晰

Relaciones Jerárquicas de Recursos

Ejemplo

# Diseño de la relación entre usuarios y artículos
class User(BaseModel):
    id: int
    name: str
    email: str

class Post(BaseModel):
    id: int
    title: str
    content: str
    author_id: int

# Operaciones sobre el recurso principal
@app.get("/users")
async def list_users() -> List[User]:
    return users

@app.get("/posts")
async def list_posts() -> List[Post]:
    return posts

# Operaciones sobre recursos relacionados
@app.get("/users/{user_id}/posts")
async def get_user_posts(user_id: int) -> List[Post]:
    """Obtener todos los artículos de un usuario específico"""
    return [post for post in posts if post.author_id == user_id]

@app.get("/posts/{post_id}/author")
async def get_post_author(post_id: int) -> User:
    """Obtener información del autor de un artículo"""
    post = find_post(post_id)
    if not post:
        raise HTTPException(status_code=404, detail="Post not found")
    return find_user(post.author_id)

Métodos HTTP y Códigos de Estado

Semántica de los Métodos HTTP

Ejemplo

from fastapi import FastAPI, status, HTTPException
from fastapi.responses import JSONResponse

app = FastAPI()

# GET - seguro e idempotente
@app.get("/users/{user_id}")
async def get_user(user_id: int):
    """Obtener un recurso sin modificar el estado del servidor"""
    user = find_user(user_id)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="User not found"
        )
    return user

# POST - no seguro y no idempotente
@app.post("/users", status_code=status.HTTP_201_CREATED)
async def create_user(user: UserCreate):
    """Crear un nuevo recurso"""
    if user_exists(user.email):
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="User already exists"
        )
    new_user = create_new_user(user)
    return new_user

# PUT - no seguro pero idempotente
@app.put("/users/{user_id}")
async def replace_user(user_id: int, user: UserUpdate):
    """Reemplazar completamente un recurso"""
    if not user_exists(user_id):
        # PUT puede crear recursos
        return create_user_with_id(user_id, user)
    return replace_existing_user(user_id, user)

# PATCH - no seguro y generalmente no idempotente
@app.patch("/users/{user_id}")
async def update_user(user_id: int, user: UserPatch):
    """Actualizar parcialmente un recurso"""
    existing_user = find_user(user_id)
    if not existing_user:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="User not found"
        )
    return patch_user_fields(existing_user, user)

# DELETE - no seguro pero idempotente
@app.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_user(user_id: int):
    """Eliminar un recurso"""
    if not user_exists(user_id):
        # Idempotencia: eliminar un recurso inexistente aún devuelve éxito
        return JSONResponse(status_code=status.HTTP_204_NO_CONTENT)
    delete_existing_user(user_id)
    return JSONResponse(status_code=status.HTTP_204_NO_CONTENT)

Uso de los Códigos de Estado HTTP

Ejemplo

from fastapi import status

# Respuestas de éxito 2xx
@app.post("/users", status_code=status.HTTP_201_CREATED)  # 201 Created
@app.get("/users")  # 200 OK (por defecto)
@app.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)  # 204 No Content

# Errores de cliente 4xx
@app.get("/users/{user_id}")
async def get_user(user_id: int):
    if user_id < 1:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,  # 400 Bad Request
            detail="User ID must be positive"
        )
   
    user = find_user(user_id)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,  # 404 Not Found
            detail="User not found"
        )
   
    return user

# Errores de lógica de negocio
@app.post("/users/{user_id}/follow")
async def follow_user(user_id: int, current_user_id: int):
    if user_id == current_user_id:
        raise HTTPException(
            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,  # 422 Unprocessable Entity
            detail="Cannot follow yourself"
        )
   
    if is_already_following(current_user_id, user_id):
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,  # 409 Conflict
            detail="Already following this user"
        )

# Errores de servidor 5xx (generalmente manejados por el procesador de excepciones)
@app.exception_handler(Exception)
async def general_exception_handler(request, exc):
    return JSONResponse(
        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,  # 500 Internal Server Error
        content={"detail": "Internal server error"}
    )

Referencia rápida de códigos de estado comunes:

# 成功状态码
200 OK                    # 请求成功
201 Created              # 资源创建成功
204 No Content           # 成功但无内容返回
206 Partial Content      # 部分内容(分页、断点续传)

# 重定向
301 Moved Permanently    # 永久重定向
302 Found               # 临时重定向
304 Not Modified        # 资源未修改(缓存)

# 客户端错误
400 Bad Request         # 请求格式错误
401 Unauthorized        # 未认证
403 Forbidden          # 已认证但无权限
404 Not Found          # 资源不存在
405 Method Not Allowed  # HTTP 方法不允许
409 Conflict           # 资源冲突
422 Unprocessable Entity # 数据验证失败
429 Too Many Requests   # 请求过于频繁

# 服务器错误
500 Internal Server Error # 服务器内部错误
502 Bad Gateway          # 网关错误
503 Service Unavailable  # 服务不可用

Formato de Datos JSON

Fundamentos de JSON y Mejores Prácticas

Ejemplo

from datetime import datetime
from decimal import Decimal
from typing import Optional, List
from pydantic import BaseModel, Field
import json

# Especificación del formato de datos JSON
class UserResponse(BaseModel):
    id: int
    username: str
    email: str
    full_name: Optional[str] = None
    is_active: bool = True
    created_at: datetime
    updated_at: Optional[datetime] = None
   
    # Configuración de serialización JSON
    class Config:
        # Permitir el uso de alias de campos
        allow_population_by_field_name = True
        # Codificador JSON
        json_encoders = {
            datetime: lambda v: v.isoformat(),
            Decimal: lambda v: float(v)
        }

# Estandarización del formato de respuesta
class APIResponse(BaseModel):
    """Formato de respuesta API estándar"""
    success: bool = True
    message: str = "Operación exitosa"
    data: Optional[dict] = None
    errors: Optional[List[str]] = None
    timestamp: datetime = Field(default_factory=datetime.now)

# Formato de respuesta paginada
class PaginatedResponse(BaseModel):
    items: List[dict]
    total: int
    page: int
    size: int
    pages: int

@app.get("/users", response_model=PaginatedResponse)
async def get_users(page: int = 1, size: int = 10):
    """Devuelve una lista paginada de usuarios"""
    users = get_users_paginated(page, size)
    total = count_users()
   
    return PaginatedResponse(
        items=users,
        total=total,
        page=page,
        size=size,
        pages=(total + size - 1) // size
    )

JSON Schema y Validación de Datos

Ejemplo

from pydantic import BaseModel, validator, Field
from typing import Optional, List
from enum import Enum

class UserRole(str, Enum):
    ADMIN = "admin"
    USER = "user"
    MODERATOR = "moderator"

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=50, description="Nombre de usuario")
    email: str = Field(..., regex=r'^[\w\.-]+@[\w\.-]+\.\w+$', description="Dirección de correo electrónico")
    password: str = Field(..., min_length=8, description="Contraseña")
    full_name: Optional[str] = Field(None, max_length=100, description="Nombre completo")
    role: UserRole = Field(UserRole.USER, description="Rol de usuario")
    age: Optional[int] = Field(None, ge=0, le=150, description="Edad")
   
    @validator('username')
    def username_must_be_alphanumeric(cls, v):
        if not v.isalnum():
            raise ValueError('El nombre de usuario solo puede contener letras y números')
        return v
   
    @validator('password')
    def password_strength(cls, v):
        if not any(c.isupper() for c in v):
            raise ValueError('La contraseña debe contener al menos una letra mayúscula')
        if not any(c.islower() for c in v):
            raise ValueError('La contraseña debe contener al menos una letra minúscula')
        if not any(c.isdigit() for c in v):
            raise ValueError('La contraseña debe contener al menos un número')
        return v

    class Config:
        # Ejemplo de generación de JSON Schema
        schema_extra = {
            "example": {
                "username": "johndoe",
                "email": "john@example.com",
                "password": "SecurePass123",
                "full_name": "John Doe",
                "role": "user",
                "age": 30
            }
        }

# Uso de validadores personalizados
@app.post("/users", response_model=UserResponse)
async def create_user(user: UserCreate):
    """Crear nuevo usuario, incluye validación de datos"""
    # Pydantic valida automáticamente los datos de entrada
    return await create_new_user(user)

Formato de Respuestas de Error

Ejemplo

class ErrorDetail(BaseModel):
    field: str
    message: str
    code: str

class ErrorResponse(BaseModel):
    error: str
    message: str
    details: Optional[List[ErrorDetail]] = None
    timestamp: datetime = Field(default_factory=datetime.now)

# Manejo de excepciones personalizado
from fastapi import Request
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    errors = []
    for error in exc.errors():
        errors.append(ErrorDetail(
            field='.'.join(str(x) for x in error['loc']),
            message=error['msg'],
            code=error['type']
        ))
   
    return JSONResponse(
        status_code=422,
        content=ErrorResponse(
            error="Validation Error",
            message="Falló la validación de los datos de la solicitud",
            details=errors
        ).dict()
    )

@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content=ErrorResponse(
            error=f"HTTP {exc.status_code}",
            message=exc.detail
        ).dict()
    )

Conceptos Específicos de FastAPI

Generación Automática de Documentación

Ejemplo

from fastapi import FastAPI, Query, Path, Body
from fastapi.openapi.utils import get_openapi

app = FastAPI(
    title="Mi API",
    description="Esta es una API de ejemplo que muestra las funcionalidades de FastAPI",
    version="1.0.0",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Desarrollador",
        "url": "http://example.com/contact/",
        "email": "developer@example.com",
    },
    license_info={
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    },
)

@app.get(
    "/users/{user_id}",
    summary="Obtener información del usuario",
    description="Obtener la información detallada del usuario según su ID",
    response_description="Objeto de información del usuario",
    tags=["Gestión de usuarios"]
)
async def get_user(
    user_id: int = Path(..., title="ID de usuario", description="El ID del usuario a obtener", ge=1),
    include_posts: bool = Query(False, title="Incluir artículos", description="Si incluir la lista de artículos del usuario")
):
    """
Obtener información del usuario:
   
- **user_id**: Identificador único del usuario
- **include_posts**: Si se incluye la lista de artículos del usuario en la respuesta
   
Devuelve la información básica del usuario; si include_posts es True, también incluirá la lista de artículos.
    """

    user = find_user(user_id)
    if include_posts:
        user.posts = get_user_posts(user_id)
    return user

# Esquema OpenAPI personalizado
def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
   
    openapi_schema = get_openapi(
        title="Documentación de API personalizada",
        version="2.5.0",
        description="Este es un esquema OpenAPI personalizado",
        routes=app.routes,
    )
   
    # Añadir información personalizada
    openapi_schema["info"]["x-logo"] = {
        "url": "https://example.com/logo.png"
    }
   
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

Vista Previa del Sistema de Inyección de Dependencias

Ejemplo

from fastapi import Depends

# Dependencia simple
def get_current_user_id() -> int:
    # Extraer el ID de usuario del token
    return 123

def get_database_session():
    # Crear sesión de base de datos
    db = DatabaseSession()
    try:
        yield db
    finally:
        db.close()

# Usar dependencia
@app.get("/profile")
async def get_profile(
    user_id: int = Depends(get_current_user_id),
    db = Depends(get_database_session)
):
    return get_user_profile(db, user_id)

# Cadena de dependencias
def get_current_user(
    user_id: int = Depends(get_current_user_id),
    db = Depends(get_database_session)
):
    return db.query(User).filter(User.id == user_id).first()

@app.get("/dashboard")
async def get_dashboard(
    current_user: User = Depends(get_current_user)  # Depende de otras dependencias
):
    return generate_dashboard(current_user)

Importancia de las Anotaciones de Tipo

Ejemplo

from typing import List, Optional, Union, Dict, Any
from pydantic import BaseModel

# FastAPI depende completamente de las anotaciones de tipo para:
# 1. Validación de datos
# 2. Generación de documentación
# 3. Soporte del editor

@app.get("/items/{item_id}")
async def get_item(
    item_id: int,  # Parámetro de ruta, convertido automáticamente a int
    q: Optional[str] = None,  # Parámetro de consulta opcional
    limit: int = 10  # Parámetro de consulta con valor predeterminado
) -> Dict[str, Any]:  # Anotación de tipo de retorno
    """Las anotaciones de tipo le indican a FastAPI cómo manejar parámetros y respuestas"""
    return {"item_id": item_id, "q": q, "limit": limit}

# Anotaciones de tipo complejas
@app.post("/items/")
async def create_items(
    items: List[ItemCreate]  # Recibe una lista de objetos ItemCreate
) -> List[ItemResponse]:     # Devuelve una lista de objetos ItemResponse
    return [create_item(item) for item in items]

# Tipo Union (varios tipos posibles)
@app.get("/search")
async def search(
    q: str,
    result_type: str = "json"
) -> Union[List[Dict], str]:  # Puede devolver una lista de diccionarios o una cadena
    if result_type == "json":
        return [{"title": "Resultado 1"}, {"title": "Resultado 2"}]
    else:
        return "Resultado 1, Resultado 2"

Ejemplo Práctico de Conceptos Clave

Ejemplo

from fastapi import FastAPI, HTTPException, status, Depends, Query
from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetime
import asyncio

# Ejemplo completo: API de blog
app = FastAPI(
    title="API de blog",
    description="Sistema de blog que demuestra los conceptos fundamentales de FastAPI",
    version="1.0.0"
)

# Modelo de datos
class PostBase(BaseModel):
    title: str = Field(..., min_length=1, max_length=200)
    content: str = Field(..., min_length=1)
    published: bool = Field(True)

class PostCreate(PostBase):
    pass

class PostResponse(PostBase):
    id: int
    author_id: int
    created_at: datetime
    updated_at: Optional[datetime] = None
   
    class Config:
        orm_mode = True

# Base de datos simulada
posts_db = []
next_id = 1

# Dependencia: obtener el usuario actual (versión simplificada)
async def get_current_user() -> int:
    # En una aplicación real, se extraería del token JWT
    return 1

# Operación de ruta asíncrona
@app.get("/posts", response_model=List[PostResponse], tags=["Artículos"])
async def list_posts(
    skip: int = Query(0, ge=0, description="Número de artículos omitidos"),
    limit: int = Query(10, ge=1, le=100, description="Número de artículos a devolver"),
    published_only: bool = Query(True, description="Solo devolver artículos publicados")
):
    """
Obtener lista de artículos
   
Admite funciones de paginación y filtrado
    """

    # Simular consulta asíncrona a la base de datos
    await asyncio.sleep(0.1)
   
    filtered_posts = posts_db
    if published_only:
        filtered_posts = [p for p in posts_db if p["published"]]
   
    return filtered_posts[skip:skip + limit]

@app.post("/posts", response_model=PostResponse, status_code=status.HTTP_201_CREATED, tags=["Artículos"])
async def create_post(
    post: PostCreate,
    current_user_id: int = Depends(get_current_user)
):
    """
Crear nuevo artículo
   
Requiere autenticación de usuario
    """

    global next_id
   
    # Simular operación asíncrona de base de datos
    await asyncio.sleep(0.1)
   
    new_post = {
        "id": next_id,
        "title": post.title,
        "content": post.content,
        "published": post.published,
        "author_id": current_user_id,
        "created_at": datetime.now(),
        "updated_at": None
    }
   
    posts_db.append(new_post)
    next_id += 1
   
    return new_post

@app.get("/posts/{post_id}", response_model=PostResponse, tags=["Artículo"])
async def get_post(post_id: int):
    """
Obtener artículo específico
   
Devuelve los detalles del artículo según su ID
    """

    # Simular consulta asíncrona a la base de datos
    await asyncio.sleep(0.1)
   
    post = next((p for p in posts_db if p["id"] == post_id), None)
    if not post:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Post with id {post_id} not found"
        )
   
    return post

# Endpoint de verificación de salud
@app.get("/health", tags=["Sistema"])
async def health_check():
    """Verificación de salud del sistema"""
    return {
        "status": "healthy",
        "timestamp": datetime.now(),
        "posts_count": len(posts_db)
    }

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
Otras extensiones