Ir al contenido

Creación de APIs Nativas (Query)

Guía de desarrollo y estructuración de metadatos para la publicación de endpoints RESTful/OData V4 de alto rendimiento en AL.

0lecturas

Para construir nuestra arquitectura de datos optimizada (ELT), nosotros desarrollamos nuestras propias APIs en lenguaje AL utilizando el objeto Query.

A diferencia de las APIs tradicionales donde programamos rutas y controladores explícitos, en AL definimos una estructura declarativa que el motor de Business Central expone automáticamente como un endpoint RESTful (OData V4).

Todo objeto query de tipo API debe comenzar con una cabecera muy estricta que define su enrutamiento y categorización.

query 50100 "Movs_Productos_API"
{
// 1. Declaración obligatoria para exponerlo como Endpoint
QueryType = API;
// 2. Enrutamiento de la URL OData
APIPublisher = 'portelcore';
APIGroup = 'api_portelcore_1';
APIVersion = 'v1.0';
// 3. Nomenclatura del recurso JSON
EntityName = 'movimiento';
EntitySetName = 'movimientos';
// 4. Integración con Power BI / Excel
QueryCategory = 'api_portelcore_1';
}
  • QueryType = API;: Esta línea es la que convierte la consulta SQL en un Web Service HTTP accesible desde el exterior.

  • Enrutamiento (El Patrón Restricto de Microsoft): La URL final que consumiremos siempre sigue este patrón inmutable: .../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}

    Nota DevSecOps: Microsoft prohíbe el uso de barras diagonales / para intentar crear “subcarpetas” lógicas. Por ello, si queremos jerarquía, usamos convenciones de nombres con guiones bajos (api_portelcore_1).

  • EntityName y EntitySetName: Definen cómo se nombran los objetos en el JSON resultante. EntitySetName (plural) será el nombre final de la tabla en la URL OData.

  • QueryCategory: Al asignar este valor, permitimos que el conector nativo de Business Central en herramientas como Excel, Power Automate o Power BI localice nuestra API de forma gráfica dentro de la carpeta “Advanced APIs”.

La sección elements de la consulta equivale a nuestra cláusula SELECT y FROM de SQL. En lugar de declarar columnas genéricas, nosotros “proyectamos” únicamente las que aportan valor analítico.

elements
{
// Esto equivale al FROM "Item Ledger Entry"
dataitem(itemLedgerEntry; "Item Ledger Entry")
{
// Las columnas proyectadas (El SELECT)
column(Tipo_Movimiento; "Entry Type") { }
column(Num_Documento; "Document No.") { }
column(Fecha_Registro; "Posting Date") { }
column(Cantidad; Quantity) { }
// Opcional: El SystemId es vital si el destino requiere una clave única o UUID
column(systemId; SystemId) { }
}
}

Como se aprecia en el código, en el lado izquierdo (column(MiNombre; "Nombre Original")) nosotros podemos rebautizar las columnas.

Esto nos permite aplicar principios de Gobierno del Dato desde el origen. Las bases de datos de Navision tienen nombres con espacios, puntos y notaciones extrañas (Shortcut Dimension 1 Code). Al reescribirlas como Cod_Dimension_1, ahorramos pasos de transformación en Power Query y entregamos un modelo analítico mucho más limpio al equipo de Business Intelligence.

  • ✓ Enrutamiento: Definición explícita de APIPublisher, APIGroup y APIVersion sin barras diagonales / para evitar fallos de compilación.
  • ✓ Gobierno: Columnas adecuadamente renombradas en origen usando notación Snake_Case limpia para facilitar el modelado.
  • ✓ Optimización: Inclusión del SystemId (UUID) para servir como clave primaria unívoca en el almacenamiento destino.