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.
Para construir nuestra arquitectura de datos optimizada (ELT), nosotros desarrollamos nuestras propias APIs en lenguaje AL utilizando el objeto Query.
A diferència de les APIs tradicionals on programem rutes i controladors explícits, en AL definim una estructura declarativa que el motor de Business Central exposa automàticament com un endpoint RESTful (OData V4).
1. Estructura i Metadades de Capçalera
Sección titulada «1. Estructura y Metadatos de Cabecera»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';}Anàlisi dels Paràmetres Crítics
Sección titulada «Análisis de los Parámetros Críticos»-
QueryType = API;
: Esta línea es la que convierte la consulta SQL en un Web Service HTTP accesible desde el exterior. -
Enrutament (El Patró Restricte de Microsoft): La URL final que consumirem sempre segueix aquest patró immutable:
.../api/{APIPublisher}/{APIGroup}/{APIVersion}/companies({id})/{EntitySetName}Nota DevSecOps: Microsoft prohibe l'ús de barres diagonal
/per intentar crear “subcarpetes” lògiques. Per això, si volem jerarquia, fem servir convencions de noms amb guions baixos (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”.
2. El Cuerpo de la Consulta (elements)
Sección titulada «2. El Cuerpo de la Consulta (elements)»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) { } } }Avantatge Arquitectònic (Column Renaming)
Sección titulada «Ventaja Arquitectónica (Column Renaming)»Como se aprecia en el código, en el lado izquierdo (column(MiNombre; "Nombre Original")) nosotros podemos rebautizar las columnas.
Això ens permet aplicar principis de Gobern de Dades des de l'origen. Les bases de dades de Navision tenen noms amb espais, punts i notacions estranyes (Shortcut Dimension 1 Code). En reescriure-les com Cod_Dimension_1, estalviem passos de transformació en Power Query i entreguem un model analític molt més net a l'equip de Business Intelligence.
3. Checklist de Validació d'API Query
Sección titulada «3. Checklist de Validación de API Query»- ✓ Enrutamiento: Definición explícita de APIPublisher
, APIGroupy APIVersionsin barras diagonales /para evitar fallos de compilación. - ✓ Gobierno: Columnas adecuadamente renombradas en origen usando notación Snake_Case limpia para facilitar el modelado.
- ✓ Optimització: Inclusió del
SystemId(UUID) per servir com a clau primària unívoca en l'emmagatzematge de destí.

