Métodos GET

Estructura básica de una API GET

Una API GET es la forma más simple de crear un punto de acceso en tu aplicación web que permite a otros programas o navegadores solicitar información. Piensa en ella como una ventana por la que otros pueden "mirar" los datos de tu aplicación sin modificarlos.

El método GET es el tipo de petición más común en internet. Cada vez que escribes una URL en tu navegador y presionas Enter, estás realizando una petición GET. En FastAPI, crear estos puntos de acceso es sorprendentemente sencillo.

Anatomía de una ruta GET

Para crear una ruta GET en FastAPI, necesitas dos elementos fundamentales: el decorador @app.get() y una función que maneje la petición.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def leer_raiz():
    return {"mensaje": "¡Hola desde FastAPI!"}

En este ejemplo básico, el decorador @app.get("/") le dice a FastAPI que cuando alguien visite la ruta raíz de tu aplicación (la URL base), debe ejecutar la función leer_raiz(). La barra diagonal "/" representa la ruta raíz, equivalente a http://localhost:8000/ cuando ejecutas tu aplicación.

Definiendo rutas específicas

Puedes crear rutas específicas para organizar mejor tu API. Cada ruta representa un recurso o funcionalidad diferente:

@app.get("/usuarios")
def obtener_usuarios():
    return {"usuarios": ["Ana", "Carlos", "María"]}

@app.get("/productos")
def obtener_productos():
    return {"productos": ["Laptop", "Mouse", "Teclado"]}

@app.get("/informacion")
def obtener_informacion():
    return {"version": "1.0", "autor": "Mi Empresa"}

Cada función asociada a una ruta debe tener un nombre único y descriptivo. FastAPI ejecutará automáticamente la función correspondiente cuando reciba una petición GET a esa ruta específica.

Convenciones de nomenclatura

Es importante seguir buenas prácticas al nombrar tus rutas y funciones:

• Rutas: Usa nombres en plural para colecciones (/usuarios, /productos) y en minúsculas
• Funciones: Usa verbos descriptivos como obtener_, leer_ o listar_
• Consistencia: Mantén un patrón coherente en toda tu aplicación

@app.get("/tareas")
def obtener_tareas():
    return {"tareas": ["Estudiar Python", "Crear API", "Hacer ejercicios"]}

@app.get("/configuracion")
def leer_configuracion():
    return {"tema": "oscuro", "idioma": "español"}

Estructura del archivo principal

Tu archivo principal de FastAPI típicamente seguirá esta estructura básica:

from fastapi import FastAPI

# Crear la instancia de la aplicación
app = FastAPI()

# Ruta raíz
@app.get("/")
def leer_raiz():
    return {"mensaje": "API funcionando correctamente"}

# Rutas adicionales
@app.get("/estado")
def verificar_estado():
    return {"estado": "activo", "servidor": "FastAPI"}

@app.get("/version")
def obtener_version():
    return {"version": "1.0.0", "framework": "FastAPI"}

La instancia app = FastAPI() debe crearse una sola vez al inicio del archivo. Todas las rutas se definen después usando esta misma instancia con sus respectivos decoradores.

Ejecutando tu API

Para probar tu API, guarda el código en un archivo (por ejemplo, main.py) y ejecuta:

uvicorn main:app --reload

Una vez ejecutándose, puedes acceder a tus rutas visitando:

• http://localhost:8000/ - Ruta raíz
• http://localhost:8000/usuarios - Lista de usuarios
• http://localhost:8000/productos - Lista de productos

FastAPI también genera automáticamente una documentación interactiva disponible en http://localhost:8000/docs, donde puedes ver todas tus rutas GET y probarlas directamente desde el navegador.

Respuestas simples con JSON

Cuando tu API responde a una petición GET, necesita enviar la información de vuelta en un formato que tanto tu aplicación como otras aplicaciones puedan entender fácilmente. JSON (JavaScript Object Notation) es el formato estándar para este intercambio de datos en las APIs modernas.

¿Qué es JSON?

JSON es un formato de texto que permite representar datos estructurados de manera simple y legible. Aunque su nombre incluye "JavaScript", se usa en prácticamente todos los lenguajes de programación, incluido Python.

Un objeto JSON se parece mucho a un diccionario de Python:

# Esto es un diccionario de Python
datos_python = {"nombre": "Ana", "edad": 25, "activo": True}

# Cuando FastAPI lo envía, se convierte automáticamente a JSON:
# {"nombre": "Ana", "edad": 25, "activo": true}

FastAPI convierte automáticamente los diccionarios de Python que devuelves en tus funciones a formato JSON. No necesitas hacer ninguna conversión manual.

Tipos de datos en JSON

JSON admite varios tipos de datos básicos que se corresponden directamente con tipos de Python:

@app.get("/tipos-datos")
def mostrar_tipos():
    return {
        "texto": "Hola mundo",           # String
        "numero_entero": 42,             # Number (entero)
        "numero_decimal": 3.14,          # Number (decimal)
        "verdadero_falso": True,         # Boolean
        "lista_numeros": [1, 2, 3, 4],   # Array
        "valor_nulo": None               # null
    }

Cuando accedas a esta ruta, FastAPI devolverá:

{
  "texto": "Hola mundo",
  "numero_entero": 42,
  "numero_decimal": 3.14,
  "verdadero_falso": true,
  "lista_numeros": [1, 2, 3, 4],
  "valor_nulo": null
}

Estructuras JSON simples

Puedes crear respuestas JSON con diferentes niveles de complejidad. Empezemos con estructuras simples:

@app.get("/usuario")
def obtener_usuario():
    return {
        "id": 1,
        "nombre": "Carlos",
        "email": "carlos@ejemplo.com"
    }

@app.get("/estadisticas")
def obtener_estadisticas():
    return {
        "usuarios_totales": 150,
        "usuarios_activos": 89,
        "porcentaje_actividad": 59.3
    }

Listas en JSON

Las listas son especialmente útiles cuando necesitas devolver múltiples elementos:

@app.get("/colores")
def obtener_colores():
    return {
        "colores_primarios": ["rojo", "azul", "amarillo"],
        "colores_favoritos": ["verde", "morado", "naranja"],
        "total_colores": 6
    }

@app.get("/numeros-pares")
def obtener_pares():
    return {
        "numeros": [2, 4, 6, 8, 10],
        "descripcion": "Primeros cinco números pares"
    }

Objetos anidados

Puedes crear estructuras más complejas anidando diccionarios dentro de otros diccionarios:

@app.get("/perfil-completo")
def obtener_perfil():
    return {
        "usuario": {
            "nombre": "María",
            "apellido": "González",
            "edad": 28
        },
        "configuracion": {
            "tema": "oscuro",
            "notificaciones": True,
            "idioma": "español"
        },
        "estadisticas": {
            "visitas": 45,
            "ultimo_acceso": "2024-01-15"
        }
    }

Respuestas dinámicas

Tus respuestas JSON pueden incluir datos calculados o generados dinámicamente:

from datetime import datetime

@app.get("/hora-actual")
def obtener_hora():
    ahora = datetime.now()
    return {
        "fecha": ahora.strftime("%Y-%m-%d"),
        "hora": ahora.strftime("%H:%M:%S"),
        "timestamp": ahora.timestamp(),
        "dia_semana": ahora.strftime("%A")
    }

@app.get("/calculo")
def realizar_calculo():
    base = 10
    exponente = 3
    resultado = base ** exponente
    
    return {
        "operacion": f"{base} elevado a {exponente}",
        "resultado": resultado,
        "tipo_calculo": "potencia"
    }

Buenas prácticas para JSON

Sigue estas recomendaciones para crear respuestas JSON claras y consistentes:

• Nombres descriptivos: Usa claves que expliquen claramente qué contienen
• Consistencia: Mantén el mismo estilo de nomenclatura en toda tu API
• Estructura lógica: Agrupa información relacionada

@app.get("/resumen-tienda")
def obtener_resumen():
    return {
        "informacion_general": {
            "nombre_tienda": "TechStore",
            "ubicacion": "Madrid",
            "telefono": "91-123-4567"
        },
        "inventario": {
            "productos_disponibles": 245,
            "categorias": ["electrónicos", "accesorios", "software"],
            "valor_total": 15750.50
        },
        "estado_operacion": {
            "abierto": True,
            "horario": "9:00 - 21:00",
            "empleados_presentes": 8
        }
    }

Verificando tus respuestas JSON

Cuando ejecutes tu API con uvicorn main:app --reload, puedes verificar que tus respuestas JSON se generan correctamente visitando las rutas en tu navegador. El navegador mostrará el JSON formateado, y también puedes usar la documentación automática en http://localhost:8000/docs para probar cada ruta y ver exactamente qué JSON devuelve.