En un proyecto Apidog, los endpoints se gestionan en una estructura jerárquica de Módulo → Carpeta → Endpoints.
- Módulos representan archivos OpenAPI independientes, generalmente agrupados por dominio de negocio o servicio.
- Carpetas organizan los endpoints por característica o función dentro de un módulo.
- Endpoints son las especificaciones OpenAPI o definiciones de API reales.
Comprender esta estructura es clave para organizar tus APIs de manera eficiente.
Aquí tienes un ejemplo de jerarquía simple:
Apidog Project
│
├── Módulo: Servicio de Usuario (dividido por dominio de negocio o servicio)
│ │
│ ├── Carpeta: Autenticación de Usuario (categoría de característica)
│ │ │
│ │ ├── Endpoint: POST /login (Iniciar Sesión)
│ │ └── Endpoint: POST /register (Registrarse)
│ │
│ └── Carpeta: Información de Usuario
│ │
│ └── Endpoint: GET /users/{id} (Obtener Información de Usuario)
│
└── Módulo: Servicio de Pedidos
│
├── Carpeta: Gestión de Pedidos
│ │
│ ├── Endpoint: POST /orders (Crear Pedido)
│ └── Endpoint: GET /orders/{id} (Obtener Detalles del Pedido)
│
└── Carpeta: Pago
│
└── Endpoint: POST /payment/submit (Enviar Pago)Comprendiendo los Módulos en Apidog
Después de comprender la jerarquía del proyecto, la siguiente pregunta es: ¿Necesita cada proyecto módulos? ¿Cuándo deberías crear uno nuevo?
Cuando creas un nuevo proyecto, Apidog genera automáticamente un módulo predeterminado. Si tu proyecto solo contiene un único servicio backend o un pequeño conjunto de endpoints, este módulo predeterminado suele ser suficiente. Sin embargo, si necesitas gestionar múltiples servicios API distintos, puedes crear un módulo separado para cada uno.
Por ejemplo, un backend de proyecto puede incluir servicios como Usuario, Producto, Pedido y Logística, cada uno responsable de un dominio específico y a menudo desplegado en diferentes URLs de servicio. En este caso, se recomienda crear módulos individuales para estos servicios para gestionar sus endpoints de forma independiente.
Puedes crear un módulo haciendo clic en el botón + encima del árbol de carpetas y seleccionando Módulo.
Una vez creado, aparece en el árbol del proyecto a la izquierda junto con otros, con su propio espacio para carpetas y endpoints. Puedes añadir libremente endpoints y carpetas dentro de cada módulo.
Los módulos son independientes entre sí, cada uno con sus propios endpoints, esquemas, componentes y variables de módulo. Sin embargo, los esquemas pueden ser referenciados entre módulos. Además, las configuraciones a nivel de proyecto, como las variables de entorno, las conexiones a bases de datos y los scripts comunes, son accesibles para todos los módulos.
Cada módulo corresponde a un archivo de especificación OpenAPI completo. Al exportar tu proyecto, los archivos OpenAPI se generan por módulo.
Comprendiendo las Carpetas dentro de un Módulo
Después de crear tus módulos, el siguiente paso es planificar cómo estructurar los endpoints dentro de ellos.
Cada módulo comienza con una carpeta raíz que contiene todas las subcarpetas y endpoints.
Puedes crear carpetas directamente bajo la raíz o anidarlas dentro de otras carpetas existentes.
Al diseñar la estructura de carpetas, considera la complejidad del módulo. Para un módulo con solo unos pocos endpoints, una carpeta simple de un solo nivel organizada por función suele ser suficiente. Pero para módulos más complejos, es mejor crear carpetas bien estructuradas y de varios niveles para mantener todo organizado y fácil de navegar.
Por ejemplo, en un módulo de Servicio de Usuario, podrías tener carpetas de nivel superior como:
- Autenticación de Usuario (para endpoints de inicio de sesión, registro, restablecimiento de contraseña)
- Información de Usuario
- Control de Acceso
Si una carpeta se vuelve demasiado grande o lógicamente independiente, puedes convertirla en un módulo independiente.
Haz clic en el icono ... junto al nombre de la carpeta y selecciona ...Más > Convertir a un nuevo Módulo. Esto ayuda a mantener la estructura de tu proyecto bien organizada a medida que escala.
Gestión de Entornos y Configuración para un Módulo
Además de los endpoints estructurados, cada módulo suele corresponder a una dirección de servicio o entorno de despliegue diferente. Puedes configurar esto fácilmente en la Gestión de Entornos.
En la configuración de gestión de entornos, la URL Base de cada módulo se puede configurar por separado. Por ejemplo, en un Entorno de Prueba:
- Servicio de Usuario →
http://user-service:8001 - Servicio de Pedidos →
http://order-service:8002
Al cambiar de entorno, Apidog actualiza automáticamente la URL base de cada módulo. Por ejemplo, al cambiar del entorno de desarrollo al de prueba, la URL base del módulo de servicio de usuario cambiará de http://localhost:8001 a http://user-service:8001, y la URL base del módulo de servicio de pedidos cambiará de http://localhost:8002 a http://order-service:8002.
Las variables de entorno se comparten entre todos los módulos y son ideales para almacenar configuraciones que difieren entre entornos. Por el contrario, las variables de módulo son únicas para cada módulo —por ejemplo, sus propias claves API o tokens— y se pueden usar en cualquier endpoint dentro de ese módulo.
Gestionando y Reutilizando Esquemas
Una gestión eficiente de esquemas ayuda a evitar duplicaciones y asegura la consistencia entre módulos.
Cada módulo tiene su propia sección de gestión de esquemas, donde puedes definir y mantener estructuras de datos relacionadas con el negocio. Estos esquemas pueden ser reutilizados dentro del módulo o referenciados por otros.
Por ejemplo, el módulo de Servicio de Usuario define esquemas relacionados con el usuario. El módulo de Servicio de Pedidos define esquemas relacionados con los pedidos. Si el Servicio de Pedidos necesita referenciar información de usuario, simplemente puede reutilizar el esquema del Servicio de Usuario, sin necesidad de recrearlo.
De Postman a Apidog: Organizando Colecciones y Endpoints Importados
Si tu equipo usaba Postman anteriormente, puedes migrar fácilmente las colecciones y endpoints existentes a Apidog.
Durante la importación:
- Cada Colección de Postman se convierte en un Módulo.
- Las estructuras de carpetas se mapean automáticamente.
- Los endpoints y esquemas se conservan.
Esto te permite mantener tu estructura API familiar mientras aprovechas el sistema modular de Apidog.
Conclusión
Al definir módulos claros, organizar carpetas y reutilizar esquemas, puedes mantener tus proyectos Apidog limpios, escalables y fáciles de colaborar.
El diseño modular de Apidog ayuda a los equipos a trabajar más rápido, evitar confusiones y gestionar APIs complejas de manera más eficiente, desde el diseño hasta la documentación y las pruebas.