Entender la API de Business Central y no morir en el intento (Parte II)

Pues vamos con la segunda parte de una serie de entradas referentes a como usar la API de Business Central en profundidad. Aquí os dejo el enlace a la primera parte Entender la API de Business Central y no morir en el intento (Parte I)

Tras esta primera parte hemos visto como obtener nuestro endpoint de conexión y como obtener los datos de algunas de las APIS estándar. Desde POSTMAN hemos logrado hacer un GET al endpoint y traer la lista de todos los Customers de nuestro Business Central

En esta entrada vamos a construir una API personalizada en nuestra extensión y así poder interactuar con los datos de la misma forma que cualquier otro método que proporciona el estándar.

Lo primero que vamos hacer es crear un proyecto nuevo en VSCode (AL: Go) y crearemos una tabla básica con su page (lista) correspondiente.

En este caso, he recuperado un proyecto donde tengo una tabla con cuatro campos básicos y la clave primaria es el campo «Code».

Pues bien, os recomiendo (no obligatorio) crear un campo de tipo GUID para poder hacer referencia desde las consultas por OData de una forma cómoda. Este campo GUID deberá de ser único por cada registro.

Para hacerlos únicos, en el OnInsert() de la tabla le asignaremos su valor con la función CreateGuid();

En caso de tener ya registros en la tabla, tendremos que tener una función para actualizar cada registro con su correspondiente GUID.

El siguiente paso consiste en crear una page de tipo API. Este tipo de page lo tenemos disponible en el atributo PageType, de todas formas, os recomiendo crearla con el snippet tpage : nos aparecerá la opción de crearla así con todas las propiedades básicas necesarias.

Al crearla nos rellenará valores por defecto en algunos atributos que tendremos que cambiar.

Caption: Es la tradicional etiqueta de la page. En mi caso la he denominado Songs.
APIPublisher: Hace referencia al publicador de la API. Al igual que tenemos un valor en el app.json para definir el editor de la APP, en la API también lo podemos definir. No tiene porque ser el mismo. En mi caso he puesto RobertoAmeijeiras.
APIGroup: Definimos un grupo al cual pertenece la API. Será como una agrupación segundaria para ver todas las APIS que pueden pertenecer a este grupo. (por si tenemos varias en un futuro)
APIVersion: La versión con la cual queremos identificar la funcionalidad de nuestra API. En mi caso v1.0
EntityName: El nombre en singular de la tabla que queremos que se muestre en el endpoint.
EntitySetName: El nombre en plural de la tabla que queremos que se muestre en el endpoint
SourceTable: La tabla de Business Central de origen de los datos.

El resto de las propiedades son las comunes al resto de pages. En mi caso quedó algo así:

El siguiente paso sería definir los campos que queremos mostrar. Yo los he sacado todos, pero en este punto podéis sólo mostrar los que se consideren.

Pues bien, con esto ya tendríamos nuestra tabla publicada en la API de Business Central. Fácil 🙂

Publicamos la APP y ya podemos consultar a través de GET los datos.
Para ello tenemos que construir nuestro endpoint.
Este se forma con la siguiente estructura:

https://<URL Base>:<Puerto>/<Instancia>/api/<API Publisher>/<API GROUP>/<API Version>/

Estos valores son los que previamente definimos a la hora de crear la page. En mi caso queda de la siguiente forma el endpoint:

En este caso ya vemos como resultado, aparte de los dos métodos estándar, la API de mysongs que es el que acabamos de crear.

Ahora ya podemos, previamente de indicar la empresa, componer el endpoint para obtener la lista de canciones que tenemos dadas de alta en Business Central. En mi caso con la empresa el endpoint queda definido de la siguiente forma:

http://host:7048/BC160_CU3/api/RobertoAmeijeiras/GrupoApp/v1.0/companies(6d24fd10-5fb7-ea11-bb3d-001dd8b76905)/mysongs

Ahora si lo que queremos es acceder a un registro en concreto, lo haremos identificándolo en este caso por la clave primaria de la tabla pasando entre () una vez llamemos a mysongs.

http://host:7048/BC160_CU3/api/RobertoAmeijeiras/GrupoApp/v1.0/companies(6d24fd10-5fb7-ea11-bb3d-001dd8b76905)/mysongs(SONG1)

De esta forma, ya solo tendremos los valores del registro SONG1.

Esto cuando la PK es simple es fácil de tratar, sin embargo, si la PK es compuesta ya se complica. Además de que, como estándares, deberíamos de hacer uso de un identificador de tipo GUID para localizar los registros.
Es aquí donde entra en juego el campo nuevo que hemos creado de tipo GUID llamado ID. Pero para que desde la API se tenga en cuenta, sólo tenemos que indicar en la page la propiedad ODataKeyFields con el campo el cual queremos hacer referencia las consultas. En nuestro caso: ID

Ahora si que podemos hacer las consultas, en vez por la PK, por los valores del campo ID.

http://host:7048/BC160_CU3/api/RobertoAmeijeiras/GrupoApp/v1.0/companies(6d24fd10-5fb7-ea11-bb3d-001dd8b76905)/mysongs(7d4f8f27-2919-4228-a306-3f829909fadf)

En el siguiente post veremos como crear, modificar o eliminar registros a través de la API en un entorno SaaS.

Que la fuerza os acompañe 🙂