Swagger on the WEB API

From version 2 of the Web API, Swagger presents itself as a documentation and invocation tool for the Web API methods, becoming the presentation page.

Modules and Versions

Since the Web API provides practically all the methods of the ERP API, and in order to guarantee high performance rates in the presentation of the interface for calling the methods, the Swagger interface is separated by module/version of the Web API.

Thus, in the combobox at the top of the page you can choose the module and its version to explore (by clicking on the Explore button):

Controllers and Methods

As discussed in the article on the characteristics of the Web API, the controllers represent each of the business entities in the selected module. The methods correspond to the services provided by the business entity.

With Swagger, you can obtain detailed information about each entity and its services by simply clicking on the items you want. Below is an example of how to edit sales document types:

In addition to the request route - HTTP Request (GET) and its description - the HTTP Response Code of the request (200 - OK), the basic format of the response and the parameters for the invocation (with their description) are displayed.

The Try it out! button allows the selected service to be launched after authentication.

Token Request

Each business entity is presented with the Login method, which allows a token (key) to be obtained for authentication in Bearer format (also known as token authentication):

In the token request, one parameter is particularly important in the context of using Primavera engines in a web context. The sessionkey must represent a unique key that will provide an integration context that is independent and isolated from other requests.

Invoking this service returns a key with the following format:

The time set for the token to expire (expired_in) can be changed in the Web.config file, in the TokenExpirationMinutes setting:

The string shown in the "access_token" item of the response corresponds to the key to be used in requests. To do this, you must pass this string to the field at the top of the page, with the prefix Bearer:

Request Invocation

After authentication and insertion of the token received in the Header Authorization field, any available service can be invoked.

Thus, taking the editing of a sales document type as an example, the invocation can be carried out after defining the respective parameters:

Token Renovation

When the token expires, a 401 - Unauthorized error is returned with the message "Authorization has been denied for this request.". In this scenario, a new token request must be made, using the same method as the first request (/token).

To ensure that the token renewal reuses the same integration context, optimizing resources and speeding up the response, the header of the new token request should indicate the previous token, which has since expired (Authorization header).

Logout

A logout endpoint is available to release resources from a given context of use.

The method is invoked without parameters, but requires the respective token to be identified in the request header (Authorization header).

This method frees up memory in the IIS process and removes sleeping sessions from the database.