Crear endpoints dinámicos con FastAPI te permite devolver datos en tiempo real, como la hora del servidor según el país solicitado. Aprenderás a registrar rutas, tipar variables y trabajar con zonas horarias usando módulos nativos de Python, ideal para quienes construyen APIs con parámetros de ruta.

¿Cómo registrar un endpoint que devuelva la hora actual en FastAPI?

Todo empieza con una función simple que retorne la hora del servidor en el momento exacto de la ejecución. La idea es exponer esa función como un endpoint accesible desde el navegador.

Dentro del archivo sync defines una función llamada time que retorne la hora actual. Para conseguirlo, importas el módulo datetime desde la librería datetime y devuelves datetime.now(). Hasta aquí tienes la lógica, pero falta exponerla como ruta.

El registro se hace con el decorador @get, al que le pasas el path time. FastAPI recarga la aplicación automáticamente y, al visitar /time en el navegador, recibes un JSON con la hora actual del servidor.

¿Qué hace el decorador @get en FastAPI? Convierte una función de Python en un endpoint HTTP accesible mediante el método GET, asociándola a la ruta que le indiques entre paréntesis.

¿Cómo recibir parámetros de ruta dinámicos en un endpoint?

Un endpoint que no recibe variables es estático y poco útil en escenarios reales. FastAPI permite recibir variables directamente desde la URL usando llaves dentro del path registrado.

En el ejemplo se usa iso_code como variable de ruta para identificar el país del cual se quiere consultar la hora. Esa variable llega como argumento a la función, pero hay un detalle importante: hay que tiparla.

¿Por qué tipar las variables con str en Python?

Tipar significa indicarle al código de qué tipo es la variable. Si pasas el cursor sobre una variable sin tipar, el editor muestra any, lo que significa cualquier tipo, y no obtienes autocompletado.

Al declarar iso_code: str, le dices al editor que la variable es de tipo string. A partir de ahí, el editor sugiere métodos disponibles como upper(), que transforma el texto a mayúsculas.

Esto importa porque las llaves del diccionario de zonas horarias están en mayúsculas. Si el usuario escribe co, Co o CO, el método upper() normaliza la entrada y evita errores de coincidencia.

¿Cómo obtener la hora por país usando zoneinfo en Python?

Con la entrada normalizada, el siguiente paso es traducir el código del país a una zona horaria válida. Aquí entran un diccionario y el módulo zoneinfo de Python.

El diccionario contiene los time zones soportados, con llaves en mayúsculas como CO o MX. Usando el método .get() del diccionario, obtienes el string de la zona horaria correspondiente al código recibido.

Luego importas zoneinfo y creas un objeto de zona horaria pasándole ese string. Ese objeto se entrega como argumento a datetime.now(tz), que devuelve la hora ajustada al time zone solicitado.

El resultado:

• Si pasas CO, la respuesta llega con offset -5.
• Si pasas MX, la respuesta llega con offset -6.
• Si escribes en minúscula o mayúscula, funciona igual gracias a upper().

¿Qué es zoneinfo en Python? Es un módulo nativo que te permite trabajar con zonas horarias usando la base de datos IANA, sin instalar librerías externas como pytz.

¿Qué ventaja tienen los parámetros de ruta dinámicos?

Los parámetros de ruta permiten que un mismo endpoint responda con información distinta según la variable enviada. En lugar de crear un endpoint por país, uno solo cubre todos los casos.

Esa flexibilidad es la base para construir APIs escalables. Puedes aplicar la misma lógica para usuarios, productos, idiomas o cualquier recurso identificable por un código.

Como reto, crea un nuevo endpoint que reciba una variable en formato GET y permita activar el formato de hora de 24 horas cuando el usuario lo requiera. ¿Cómo lo resolverías tú? Cuéntame en los comentarios.