Construir una API que devuelva la hora según el país del usuario es un ejercicio práctico que reúne varios fundamentos de FastAPI, el manejo de zonas horarias en Python y el uso de parámetros de ruta. A continuación se explica paso a paso cómo lograrlo, desde un endpoint estático hasta uno completamente dinámico.
¿Cómo devolver la hora del servidor con FastAPI?
El punto de partida es crear una función sencilla que retorne la hora actual del servidor. Para ello se importa el módulo datetime y se define una función decorada con @app.get [0:06].
python
from datetime import datetime
@app.get("/time")
def time():
return datetime.now()
Al registrar esta función como endpoint con el decorador get, FastAPI expone automáticamente la ruta /time. Cuando se visita desde el navegador, el servidor responde con un JSON que contiene la fecha y hora actuales [0:30].
Sin embargo, un endpoint que no recibe variables es estático y poco útil en escenarios reales. FastAPI permite recibir variables directamente dentro de la URL, lo que se conoce como parámetros de ruta.
¿Qué son los parámetros de ruta y cómo se tipan?
Para convertir el endpoint en dinámico, se agrega una variable entre llaves dentro de la ruta. En este caso, iso_code representa el código de país [0:50].
python
@app.get("/time/{iso_code}")
def time(iso_code: str):
...
¿Por qué es importante el tipado en Python?
Cuando se declara iso_code sin tipo, el editor lo interpreta como any y no ofrece autocompletado. Al agregar : str, se le indica al código que la variable será de tipo string [1:08]. Esto activa las sugerencias del editor y permite aplicar métodos como .upper(), que transforma el texto a mayúsculas sin importar cómo lo escriba el usuario.
- Si el usuario envía
co, Co o CO, el resultado siempre será CO.
- Esta normalización evita errores al buscar en un diccionario cuyas llaves están en mayúsculas.
¿Cómo se utiliza un diccionario de zonas horarias?
Se define un diccionario donde cada llave es un código ISO en mayúsculas y el valor es el timezone correspondiente [1:35].
python
time_zones = {
"CO": "America/Bogota",
"MX": "America/Mexico_City",
"AR": "America/Argentina/Buenos_Aires",
"PE": "America/Lima",
}
Con el método .get() del diccionario se obtiene el timezone como string:
python
tz_str = time_zones.get(iso_code.upper())
¿Cómo obtener la hora en una zona horaria específica?
Python incluye el módulo zoneinfo, que permite crear objetos de zona horaria a partir de un string. Se importa ZoneInfo y se pasa como argumento a datetime.now() [2:05].
python
from zoneinfo import ZoneInfo
@app.get("/time/{iso_code}")
def time(iso_code: str):
tz_str = time_zones.get(iso_code.upper())
tz = ZoneInfo(tz_str)
return datetime.now(tz)
El resultado es inmediato:
/time/co devuelve la hora con UTC-5 (Colombia)./time/mx devuelve la hora con UTC-6 (México)./time/MX funciona igual gracias a .upper() [2:30].
Los parámetros de ruta hacen que los endpoints sean dinámicos, permitiendo devolver información distinta según las variables recibidas en la URL. Esto abre la puerta a construir APIs flexibles con múltiples rutas basadas en datos del usuario.
Como reto, intenta crear un nuevo endpoint que reciba un parámetro query (formato GET) para que el usuario elija si quiere la hora en formato de 24 horas o de 12 horas. ¿Te animas a compartir tu solución?
