Skip to content

Capítulo 3.2: Creación del primer endpoint de API

Tiempo de estudio: 30 minutos


1. Endpoint: Puerto de acoplamiento para datos

Imagine que nuestra API es una estación espacial. Un Endpoint (punto final) es un puerto de acoplamiento específico, diseñado para un tipo particular de naves.

  • Puerto №1 — para naves de carga (datos sobre planetas).
  • Puerto №2 — para sondas de investigación (datos sobre misiones).
  • Puerto №3 — para transbordadores de pasajeros (datos sobre astronautas).

Cada endpoint es una URL única que se encarga de una operación específica con un recurso particular.

💡 Analogía espacial: GET /spaceships — es el comando "Control de Misión → Estación: Informe la lista de todas las naves acopladas". Este endpoint devuelve una colección de recursos.


2. Creación de una "flota espacial"

Como todavía no tenemos una base de datos, crearemos una "simulación": una lista simple de naves espaciales en forma de diccionario de Python.

Abra main.py y añada este código antes de la definición de app:

# main.py

# Paso 1: Creamos una simulación de base de datos
db_spaceships = {
    1: {
        "name": "Voyager-1",
        "type": "Sonda",
        "launch_year": 1977,
        "status": "Activo"
    },
    2: {
        "name": "Hubble Space Telescope",
        "type": "Telescopio",
        "launch_year": 1990,
        "status": "Activo"
    },
    3: {
        "name": "ISS",
        "type": "Estación",
        "launch_year": 1998,
        "status": "En órbita"
    }
}

# ... aquí el código app = FastAPI()
Este es nuestro "registro de naves espaciales" con el que trabajaremos.


3. Primer endpoint: Lista de naves

Ahora crearemos un endpoint que devolverá toda nuestra flota.

Añada este código en main.py después de @app.get("/"):

# main.py

# ... código con db_spaceships, FastAPI, app y read_root() ...

@app.get("/spaceships")
def get_spaceships():
    """
    Devuelve una lista de todas las naves espaciales en el registro.
    """
    return db_spaceships

  • @app.get("/spaceships"): Hemos creado una nueva ruta. Ahora las solicitudes GET a la URL /spaceships serán manejadas por la función get_spaceships.
  • return db_spaceships: FastAPI convertirá automáticamente el diccionario de Python en una respuesta JSON correcta.

4. Verificación del funcionamiento del nuevo puerto de acoplamiento

Si su servidor uvicorn todavía está en ejecución con la bandera --reload, ya se habrá recargado y estará listo para funcionar. Si no, ejecútelo de nuevo:

uvicorn main:app --reload

Paso 1: Verificación en el navegador

Abra en el navegador la dirección http://127.0.0.1:8000/spaceships. Debería ver la lista completa de sus naves en formato JSON:

{
  "1": {
    "name": "Voyager-1",
    "type": "Sonda",
    "launch_year": 1977,
    "status": "Activo"
  },
  "2": {
    "name": "Hubble Space Telescope",
    "type": "Telescopio",
    "launch_year": 1990,
    "status": "Activo"
  },
  "3": {
    "name": "ISS",
    "type": "Estación",
    "launch_year": 1998,
    "status": "En órbita"
  }
}

Paso 2: Verificación en la autodocumentación

Vaya a http://127.0.0.1:8000/docs. Verá que en la documentación ha aparecido una nueva sección para el endpoint GET /spaceships. ¡Puede hacer clic en "Try it out" y "Execute" para probarlo directamente desde allí!


5. Endpoint con parámetro: Datos sobre una nave específica

¿Qué pasa si solo necesitamos datos sobre el "Voyager-1"? Para ello, crearemos un endpoint con un parámetro de ruta (path parameter).

Añada este código en main.py:

# main.py

# ... resto del código ...

@app.get("/spaceships/{ship_id}")
def get_spaceship(ship_id: int):
    """
    Devuelve datos sobre una nave espacial específica por su ID.
    """
    return db_spaceships.get(ship_id)

  • "/spaceships/{ship_id}": Los corchetes {} le dicen a FastAPI que ship_id es una variable que se pasará desde la URL.
  • ship_id: int: Esto es una pista de tipo (type hint). FastAPI verificará automáticamente que el ID pasado es un número entero. Si alguien solicita /spaceships/voyager, FastAPI devolverá un error de validación 422 Unprocessable Entity. ¡Esto es magia!

Verificación:

Abra http://127.0.0.1:8000/spaceships/2. Debería obtener datos solo sobre el telescopio "Hubble". Y si abre http://127.0.0.1:8000/spaceships/99 — obtendrá null, ya que esa nave no existe.


Cuestionario para consolidar

1. Un endpoint en una API es...

2. ¿Qué hace el decorador `@app.get("/users")`?

3. ¿Qué significa la entrada `"/items/{item_id}"` en la ruta?

4. ¿Por qué se necesita la pista de tipo `ship_id: int` en la función?

5. Si solicita `/spaceships/abc` y FastAPI espera un `int`, ¿qué sucederá?


🚀 Resumen del capítulo:

Ha creado con éxito dos "puertos de acoplamiento" en su estación espacial API:

  • 🛰️ Uno para obtener la lista de todas las naves (/spaceships)
  • 🔭 Otro para obtener datos sobre una nave específica (/spaceships/{ship_id})

También ha visto el poder de la validación automática de tipos de FastAPI, que protege su API de solicitudes incorrectas.

¡El sistema de navegación está configurado! En el próximo capítulo, crearemos "planos" para nuestras naves espaciales usando Pydantic, para hacer nuestra API aún más inteligente y robusta.

📌 Verificación: - El servidor uvicorn está iniciado y funcionando. - La URL http://127.0.0.1:8000/spaceships devuelve un JSON con la lista de naves espaciales. - La URL http://127.0.0.1:8000/spaceships/1 devuelve datos sobre el "Voyager-1". - La URL http://127.0.0.1:8000/docs muestra dos nuevos endpoints.

⚠️ Si hay errores:

  • 404 Not Found: Compruebe que la URL está escrita correctamente en el navegador y en el decorador @app.get(...).
  • Error en el código: Revise cuidadosamente la sintaxis, especialmente las indentaciones en Python y las comas en el diccionario.