Estructuración de Aplicaciones con FastAPI y API Router

La organización de endpoints en una aplicación es crucial para mantener el código limpio y fácil de escalar. Cuando todos los endpoints están en un solo archivo, se vuelve complicado de manejar y actualizar, especialmente en aplicaciones robustas. Para evitar esto, FastAPI permite estructurar la aplicación con un enfoque modular, utilizando routers y etiquetado, facilitando su mantenimiento.

¿Por qué dividir los endpoints en múltiples archivos?

Tener todos los endpoints en un solo archivo lleva a un código excesivamente largo y difícil de modificar. Dividir los endpoints en archivos separados permite:

• Mantener una estructura limpia y organizada.
• Facilitar la búsqueda y edición de endpoints específicos.
• Aumentar la claridad y reducir los errores al trabajar en el código.

¿Cómo configurar la estructura de archivos en FastAPI?

FastAPI recomienda crear una carpeta principal para la aplicación. Dentro de esta carpeta, se agregan varios archivos y subcarpetas:

• __init__.py: convierte la carpeta en un módulo, permitiendo importar archivos de forma más sencilla.
• main.py: contiene la configuración principal de la aplicación, incluyendo las dependencias y la raíz de la aplicación.
• dependencies.py: archivo para definir dependencias comunes a varios endpoints.
• routers/: subcarpeta que agrupa endpoints específicos, como customer, transactions, e invoices.

Otros archivos recomendados incluyen db.py para la configuración de la base de datos y models.py para los modelos de datos. En aplicaciones con muchos modelos, se recomienda dividir estos en múltiples archivos dentro de un módulo.

¿Qué es el API router y cómo agrupa endpoints?

El API router es como una mini aplicación dentro de FastAPI que permite agrupar y organizar endpoints relacionados. Este agrupamiento facilita el soporte y la implementación de cambios en los endpoints específicos sin afectar el resto. Cada router puede manejar un recurso en particular, como customer, transactions o invoices.

Ejemplo de configuración de router

1. En la carpeta routers/, creamos un archivo como customer.py.
2. Copiamos los endpoints de customer a este archivo y realizamos los imports necesarios, como:
   • models para acceder a los modelos de datos.
   • DB para la configuración de la base de datos.
   • APIRouter de FastAPI para definir el router.
3. Modificamos el código para usar router en lugar de app, y así consolidamos el router de customer.

¿Cómo registrar routers y resolver errores comunes?

Al mover los endpoints a un archivo específico, debemos registrarlos en main.py usando include_router. Si al ejecutar la aplicación se encuentran errores, pueden ser causados por imports incorrectos. Es común que:

• Los imports de models o DB requieran ajustes en las rutas de acceso.
• Los routers deben incluir el punto y la ruta correcta, como routers.customer.

¿Cómo agrupar endpoints con tags en FastAPI?

Agregar etiquetas (tags) permite que los endpoints aparezcan agrupados en la documentación. Esto se logra fácilmente con FastAPI, lo que ayuda a:

• Identificar rápidamente endpoints relacionados en la documentación.
• Facilitar la navegación para desarrolladores y usuarios de la API.

Ejemplo de etiquetado en un router

Dentro del archivo del router (customer.py):

• Agregamos tags=["customer"] en cada endpoint.
• Así, en la documentación, todos los endpoints de customer aparecerán agrupados bajo esta etiqueta.