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()
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 solicitudesGET
a la URL/spaceships
serán manejadas por la funciónget_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:
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 queship_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ón422 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
🚀 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 URLhttp://127.0.0.1:8000/spaceships
devuelve un JSON con la lista de naves espaciales. - La URLhttp://127.0.0.1:8000/spaceships/1
devuelve datos sobre el "Voyager-1". - La URLhttp://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.