Referencia técnica

• Open API Specification
• Documentación Interactiva (Rapidocus)
• Diagrama entidad-relación (ERD)

Open API Specification

Catalogo ofrece una API REST para consumir los datos en la base de datos. La API tiene direcciones URL predecibles orientadas a los recursos, se basa en códigos de estado HTTP estándar y utiliza JSON para la entrada y la salida de datos.

Open API Specification

Catalogo tiene un endpoint para mostrar las especificaciones Open API para describir y/o detallar el API REST. La idea es que los desarrolladores puedan hacer pruebas de manera más intuitivas.

Para obtener las especificaciones pueden usar el siguiente endpoint:

GET /server/specs/oas

Una vez tengan las especificaciones del API, pueden usar el Editor de Swagger u otro, pegar las especificaciones en el editor para generar dinámicamente todos los endpoints existentes a los que su usuario tiene acceso.

Documentación Interactiva (Rapidocus)

La documentación interactiva es una herramienta integrada en la plataforma del Catálogo de Servicios que permite a los desarrolladores explorar, probar y entender los endpoints del API de manera visual e intuitiva, sin necesidad de instalar aplicaciones externas. 

Esta sección proporciona un espacio donde cualquier usuario técnico puede aprender rápidamente cómo funciona el API, ver cómo se estructuran las llamadas y comprender de forma más profunda las respuestas y parámetros disponibles, reduciendo el tiempo de aprendizaje.

¿Qué es la documentación interactiva?

Es una interfaz dinámica disponible desde el panel del Catálogo que permite:

• Navegar por todos los endpoints del API organizados por categorías.

• Consultar descripciones, parámetros y respuestas de cada endpoint.

• Probar los endpoints directamente desde la interfaz (con un botón "Try"), utilizando tus credenciales y tokens válidos.

• Ver ejemplos de solicitudes y respuestas en tiempo real.

• Ajustar cómo se visualiza la información (filtros, formato de código, organización de secciones).

¿Cómo acceder?

1. Ingresa al panel del Catálogo con tus credenciales.

2. Dirígete a la URL /admin/rapidocus

3. Selecciona la categoría de endpoints que quieras explorar (por ejemplo,  Services).

Funciones principales

• Exploración por categorías: Los endpoints están organizados según los recursos del API, para facilitar la búsqueda.

• Pruebas en vivo (Try): Permite ejecutar solicitudes GET, POST, PUT o DELETE directamente, utilizando tus tokens y parámetros, y ver la respuesta al instante.

• Visualización personalizable: Puedes cambiar la forma en que se presentan los resultados (código resaltado, JSON plano o estructurado, etc.).

• Filtros avanzados: Permite buscar endpoints o parámetros específicos con un cuadro de búsqueda.

• Copiar ejemplos: Incluye botones para copiar al portapapeles ejemplos de requests y respuestas.

¿Por qué usarla?

• Evita configurar herramientas externas como Postman para pruebas iniciales.

• Acelera el aprendizaje de cómo funciona cada endpoint y qué datos retorna.

• Facilita la depuración durante el desarrollo, ya que puedes confirmar rápidamente si el API está respondiendo como se espera.

Recomendaciones de uso

• Siempre inicia sesión con un usuario válido antes de probar endpoints protegidos.

• Utiliza primero el entorno de sandbox para realizar pruebas, antes de interactuar con producción.

• Respeta los límites de consumo (SLA) al ejecutar múltiples pruebas.

• Para integraciones reales, utiliza la guía "Quick Start" y la referencia completa del API (OpenAPI) en combinación con esta herramienta.

 

Diagrama entidad-relación (ERD)

Esta sección proporciona una vista estructurada de las relaciones entre las entidades clave del sistema de Catálogo de Servicios. El diagrama resulta útil para entender cómo se conectan los diferentes componentes del sistema, facilitando tareas de integración, depuración o generación de reportes.

📌 ¿Qué muestra este diagrama?

• Relación entre servicios y sus variaciones

• Asociación con canales de atención, oficinas, requisitos, documentos, resultados y URLs

• Vínculos con clasificaciones, tipos, estados y usuarios responsables

🔗 Acceso al diagrama interactivo

Puedes acceder al diagrama en tiempo real desde el siguiente enlace:

👉 Ver ERD interactivo

Este diagrama es interactivo y permite navegar visualmente por las relaciones entre las tablas, haciendo clic sobre cada entidad para ver sus campos y claves foráneas.

🧠 Casos de uso comunes

• Comprender la estructura de datos para integraciones externas (ej. Power BI, ETL, etc.)

• Diagnosticar errores o relaciones faltantes en servicios

• Crear consultas SQL más precisas

• Diseñar APIs o apps externas basadas en el modelo del Catálogo