Generación de URL

Generar URLs de Entidades

GET /api/{tenantId}/url/generate

Genera URLs directas a páginas y entidades de mindzieStudio. Esta API crea URLs con el formato correcto para navegar a proyectos, paneles, investigaciones, notebooks, bloques y otras entidades.

Autenticación

Requiere autenticación con token Bearer:

Authorization: Bearer {api_key}

Solicitud

GET /api/{tenantId}/url/generate?type={urlType}&entityId={id}&parentId={parentId}
Authorization: Bearer {token}

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
tenantId	GUID	Sí	Identificador del tenant

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
type	String	Sí	Tipo de URL a generar (ver Tipos de URL abajo)
entityId	GUID	Condicional	ID de la entidad para páginas específicas de entidad
parentId	GUID	Condicional	ID del padre (projectId o notebookId dependiendo del tipo)
baseUrl	String	No	Sobrescribe la URL base (por defecto es el origen de la solicitud)

Tipos de URL

Páginas de Listado

Estos tipos de URL retornan URLs directas a páginas de listas/índices:

Tipo	parentId requerido	Patrón de URL Generada
projects	No	/projects?tenantId={tenantId}
apps	No	/apps?tenantId={tenantId}
investigations	Sí (projectId)	/investigations?projectId={parentId}
dashboards-list	Sí (projectId)	/dashboards?projectId={parentId}
datasets	Sí (projectId)	/manage-datasets?projectId={parentId}
actions	Sí (projectId)	/actions?projectId={parentId}
bpmn	Sí (projectId)	/bpmn-editor?projectId={parentId}

Páginas de Entidad

Estos tipos de URL retornan URLs /navigate que enrutan a entidades específicas:

Tipo	entityId	parentId	Descripción
dashboard	dashboardId	-	Vista de un solo panel
analysis	notebookId	-	Página de notebook/análisis
block	blockId	notebookId	Bloque específico en una página de notebook
enrichment	enrichmentNotebookId	projectId (opcional)	Notebook de enriquecimiento

Respuesta

Estructura de la Respuesta

{
  "url": "https://your-instance.mindziestudio.com/projects?tenantId=...",
  "entityType": "projects",
  "entityId": null,
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

Campos de la Respuesta

Campo	Tipo	Descripción
url	String	La URL completa para la página o entidad solicitada
entityType	String	El tipo de URL generada (coincide con el parámetro type)
entityId	GUID o null	ID de la entidad si se generó una URL específica para entidad
tenantId	GUID	ID del tenant usado en la solicitud

Ejemplos

Páginas de Listado

Obtener URL de la Lista de Proyectos

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=projects"

Respuesta:

{
  "url": "https://host/projects?tenantId=660e8400-e29b-41d4-a716-446655440000",
  "entityType": "projects",
  "entityId": null,
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

Obtener Investigaciones para un Proyecto

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=investigations&parentId={projectId}"

Respuesta:

{
  "url": "https://host/investigations?projectId=770e8400-e29b-41d4-a716-446655440001",
  "entityType": "investigations",
  "entityId": null,
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

Obtener Lista de Dashboards para un Proyecto

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=dashboards-list&parentId={projectId}"

Páginas de Entidad

Enlace Directo a un Dashboard

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=dashboard&entityId={dashboardId}"

Respuesta:

{
  "url": "https://host/navigate?type=dashboard&id=880e8400-e29b-41d4-a716-446655440002",
  "entityType": "dashboard",
  "entityId": "880e8400-e29b-41d4-a716-446655440002",
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

Enlace Directo a un Notebook/Análisis

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=analysis&entityId={notebookId}"

Enlace Directo a un Bloque Específico

curl -H "Authorization: Bearer {api_key}" \
  "https://host/api/{tenantId}/url/generate?type=block&entityId={blockId}&parentId={notebookId}"

Respuesta:

{
  "url": "https://host/navigate?type=block&id=990e8400-e29b-41d4-a716-446655440003&notebookId=aa0e8400-e29b-41d4-a716-446655440004",
  "entityType": "block",
  "entityId": "990e8400-e29b-41d4-a716-446655440003",
  "tenantId": "660e8400-e29b-41d4-a716-446655440000"
}

Ejemplo en JavaScript

class UrlGenerator {
  constructor(baseUrl, tenantId, token) {
    this.baseUrl = baseUrl;
    this.tenantId = tenantId;
    this.headers = {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
  }

  async generateUrl(type, options = {}) {
    const params = new URLSearchParams({ type });

    if (options.entityId) {
      params.append('entityId', options.entityId);
    }
    if (options.parentId) {
      params.append('parentId', options.parentId);
    }
    if (options.baseUrl) {
      params.append('baseUrl', options.baseUrl);
    }

    const response = await fetch(
      `${this.baseUrl}/api/${this.tenantId}/url/generate?${params}`,
      { headers: this.headers }
    );

    if (!response.ok) {
      throw new Error(`Failed to generate URL: ${response.status}`);
    }

    return response.json();
  }

  // Métodos de conveniencia
  async getProjectsUrl() {
    return this.generateUrl('projects');
  }

  async getInvestigationsUrl(projectId) {
    return this.generateUrl('investigations', { parentId: projectId });
  }

  async getDashboardUrl(dashboardId) {
    return this.generateUrl('dashboard', { entityId: dashboardId });
  }

  async getBlockUrl(blockId, notebookId) {
    return this.generateUrl('block', {
      entityId: blockId,
      parentId: notebookId
    });
  }
}

// Uso
const urlGen = new UrlGenerator(
  'https://your-instance.mindziestudio.com',
  'tenant-guid',
  'your-api-token'
);

// Obtener URL a la lista de proyectos
const projectsUrl = await urlGen.getProjectsUrl();
console.log('Projects URL:', projectsUrl.url);

// Obtener URL a un dashboard específico
const dashboardUrl = await urlGen.getDashboardUrl('dashboard-guid');
console.log('Dashboard URL:', dashboardUrl.url);

// Obtener URL a un bloque específico
const blockUrl = await urlGen.getBlockUrl('block-guid', 'notebook-guid');
console.log('Block URL:', blockUrl.url);

Ejemplo en Python

import requests
from typing import Optional, Dict, Any

class UrlGenerator:
    def __init__(self, base_url: str, tenant_id: str, token: str):
        self.base_url = base_url
        self.tenant_id = tenant_id
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def generate_url(
        self,
        url_type: str,
        entity_id: Optional[str] = None,
        parent_id: Optional[str] = None,
        base_url_override: Optional[str] = None
    ) -> Dict[str, Any]:
        """Genera una URL para el tipo y entidad especificados"""
        params = {'type': url_type}

        if entity_id:
            params['entityId'] = entity_id
        if parent_id:
            params['parentId'] = parent_id
        if base_url_override:
            params['baseUrl'] = base_url_override

        url = f"{self.base_url}/api/{self.tenant_id}/url/generate"
        response = requests.get(url, params=params, headers=self.headers)
        response.raise_for_status()
        return response.json()

    # Métodos de conveniencia para páginas de listas
    def get_projects_url(self) -> str:
        return self.generate_url('projects')['url']

    def get_investigations_url(self, project_id: str) -> str:
        return self.generate_url('investigations', parent_id=project_id)['url']

    def get_dashboards_list_url(self, project_id: str) -> str:
        return self.generate_url('dashboards-list', parent_id=project_id)['url']

    def get_datasets_url(self, project_id: str) -> str:
        return self.generate_url('datasets', parent_id=project_id)['url']

    def get_actions_url(self, project_id: str) -> str:
        return self.generate_url('actions', parent_id=project_id)['url']

    # Métodos de conveniencia para páginas de entidad
    def get_dashboard_url(self, dashboard_id: str) -> str:
        return self.generate_url('dashboard', entity_id=dashboard_id)['url']

    def get_analysis_url(self, notebook_id: str) -> str:
        return self.generate_url('analysis', entity_id=notebook_id)['url']

    def get_block_url(self, block_id: str, notebook_id: str) -> str:
        return self.generate_url('block', entity_id=block_id, parent_id=notebook_id)['url']

    def get_enrichment_url(self, enrichment_id: str, project_id: Optional[str] = None) -> str:
        return self.generate_url('enrichment', entity_id=enrichment_id, parent_id=project_id)['url']


# Uso
url_gen = UrlGenerator(
    'https://your-instance.mindziestudio.com',
    'tenant-guid',
    'your-api-token'
)

# Obtener varias URLs
projects_url = url_gen.get_projects_url()
print(f"Projects: {projects_url}")

investigations_url = url_gen.get_investigations_url('project-guid')
print(f"Investigations: {investigations_url}")

dashboard_url = url_gen.get_dashboard_url('dashboard-guid')
print(f"Dashboard: {dashboard_url}")

block_url = url_gen.get_block_url('block-guid', 'notebook-guid')
print(f"Block: {block_url}")

Integración con MCP Server

Los asistentes de codificación AI pueden generar URLs usando el servidor MCP:

mindzie_generate_url type="dashboard" entityId="{dashboardId}"

Ver Integración con MCP Server para la documentación completa.

Casos de Uso

Compartir Enlaces

Generar URLs compartibles a dashboards específicos, investigaciones o bloques de análisis.

Flujos de Trabajo de Integración

Crear enlaces de navegación en sistemas externos que enlacen profundamente en mindzieStudio.

Navegación por Asistente AI

Permitir que herramientas AI generen y abran páginas específicas en la aplicación.

Reportes Automatizados

Incluir enlaces directos a dashboards o análisis relevantes en reportes automatizados.

Manejo de Errores

Código de Estado	Descripción
200	Éxito - URL generada
400	Solicitud incorrecta - Tipo inválido o parámetros requeridos faltantes
401	No autorizado - Token de autenticación inválido o faltante
404	No encontrado - Entidad no encontrada (para URLs específicas de entidad)