Swagger en la WEB API

A partir de la versión 2 de la Web API, Swagger se presenta como la herramienta de documentación e invocación de los métodos de la Web API, convirtiéndose en la página de presentación.

Módulos y versiones

Dado que la Web API ofrece prácticamente todos los métodos de la API del ERP, y con el fin de garantizar altos índices de rendimiento en la presentación de la interfaz de llamada a los métodos, la interfaz de Swagger está separada por módulo/versión de la Web API.

Así, en el combobox de la parte superior de la página, puede elegir el módulo y su versión para explorar (haciendo clic en el botón Explore):

Controllers y Métodos

Tal como se discutió en el artículo sobre las características de la Web API, los controllers representan cada una de las entidades de negocio del módulo seleccionado. Los métodos corresponden a los servicios prestados por la entidad de negocio.

Con Swagger, se puede obtener información detallada sobre cada entidad y sus servicios simplemente haciendo clic en los elementos deseados.  A continuación se muestra un ejemplo de cómo editar los tipos de documentos de venta:

Además de la ruta de la petición - HTTP Request (GET) y respectiva descripción - se presenta el HTTP Response Code de la petición (200 - OK), el formato base de la respuesta y los parámetros para la invocación (con su descripción).

El botón Try it out! permite lanzar el servicio seleccionado tras la autenticación.

Petición de token

Para cada entidad de negocio, se muestra el método Login que permite obtener un token (clave) para la autenticación en formato Bearer (también conocido como de autenticación vía token):

En la petición del token, un parámetro es particularmente importante en el contexto de la utilización de los motores Primavera en un contexto web. La clave de sesión debe representar una clave única que proporcionará un contexto de integración independiente y aislado de las demás peticiones.

La invocación de este servicio devuelve una clave con el siguiente formato:

El tiempo definido para que caduque el token (expired_in) puede modificarse en el archivo Web.config, en el parámetro TokenExpirationMinutes:

El string que aparece en el ítem "access_token" de la respuesta corresponde a la clave que se utilizará en las peticiones. Para ello, debe pasar este string al campo de la parte superior de la página, con el prefijo Bearer:

Invocación de una petición

Tras la autenticación y la inserción del token recibido en el campo Header Authorization, se puede invocar cualquier servicio disponible.

Así, tomando como ejemplo la edición de un tipo de documento de venta, la invocación puede realizarse tras definir los respectivos parámetros:

Renovación de token

Cuando el token caduca, se devuelve un error 401 - Unauthorized con el mensaje "Authorization has been denied for this request.". En este escenario, deberá realizar una nueva petición token, utilizando el mismo método que en la primera petición (/token).

Para que la renovación del token reutilice el mismo contexto de integración, garantizando la optimización de los recursos y una respuesta más rápida, deberá indicar en el header de la petición de nuevo token, el token anterior, ya caducado (header Authorization).

Logout

Está disponible un endpoint de logout que permite liberar recursos de un determinado contexto de uso.

El método se invoca sin parámetros, pero implica la identificación del token respectivo en el header de la petición (header Authorization).

Este método permite liberar memoria en el proceso del IIS, así como eliminar sesiones sleeping de la base de datos.