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
- Alto Rendimiento: comparable con NodeJS y Go, es uno de los frameworks de Python más rápidos
- Desarrollo Rápido: velocidad de desarrollo aproximadamente 200%-300% mayor
- Menos Errores: reduce aproximadamente un 40% de errores humanos
- Intuitivo: potente soporte de editores, autocompletado en todas partes
- 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',
})
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
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
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}
@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)
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)
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)
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"}
)
# 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
)
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)
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()
)
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
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)
# 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"
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)
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)