¿Cómo define rutas (operaciones de ruta)?

Question

Accepted Answer

En FastAPI, una **operación de ruta** es una ruta — una función decorada con un decorador de método HTTP (`@app.get`, `@app.post`, etc.) que maneja solicitudes a una ruta. El valor de retorno de la función se serializa automáticamente a JSON.

## Definición de rutas para cada método HTTP

```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/items")                # GET /items
def list_items():
    return [{"id": 1}, {"id": 2}]  # dict/list → automatically JSON-serialized

@app.get("/items/{item_id}")      # GET /items/5 — path parameter
def get_item(item_id: int):        # type hint converts "5" → int (and validates)
    return {"id": item_id}

@app.post("/items")               # POST /items
def create_item(item: Item):
    return item

@app.put("/items/{item_id}")      # PUT, PATCH, DELETE work the same way
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"deleted": item_id}
```

Cada decorador asigna un método HTTP + ruta a un controlador. El nombre de la función es suyo; el decorador define la ruta. Los dicts/listas/modelos Pydantic devueltos se serializan automáticamente a JSON — sin `json.dumps` manual.

## El orden importa para rutas superpuestas

```python
@app.get("/users/me")            # ✅ specific route FIRST
def read_me(): ...
@app.get("/users/{user_id}")     # dynamic AFTER — else "me" matches {user_id}
def read_user(user_id: int): ...
```

FastAPI coincide con las rutas en el orden de declaración, así que coloque rutas estáticas antes de dinámicas.

## Metadatos de operación (impulsan los docs)

```python
@app.get("/items", tags=["items"], summary="List items", status_code=200)
def list_items(): ...
```

Los parámetros del decorador (`tags`, `summary`, `status_code`, `response_model`) configuran el comportamiento y enriquecen la documentación generada automáticamente.

## Por qué es importante

Las operaciones de ruta son el fundamento de toda aplicación FastAPI — definen los puntos finales de su API y cómo se manejan las solicitudes.

Comprender el patrón decorador-por-método-HTTP, que los valores de retorno se serializan automáticamente a JSON (sin código repetitivo), que las anotaciones de tipo en parámetros impulsan la conversión y validación, y que el orden de rutas importa para rutas superpuestas es conocimiento esencial cotidiano para construir cualquier punto final.

Los metadatos del decorador también alimentan la documentación automática de FastAPI, vinculando las rutas directamente a los docs.

Esta es la primera y más fundamental cosa que dominar en FastAPI.