Version 2 of the Web API

Version 2 of the Web API in ERP version 10 presents some significant changes compared to the previous version:

• Responses now have a single structure for all methods;
• Use of 4 types of HTTP Request (GET, POST, PUT, DELETE);
• Blocking simultaneous requests for the same integration context;
• Use of Swagger as a tool for documenting and invoking requests.

Endpoints

All version 2 endpoints will now be supplemented with v2 before the module is identified.

Thus, the basic URL structure of the endpoints becomes:

http://localhost:2018/WebApi/v2/{modulo}/{entidade}/{servico}/

Request Return

In version 2, the response to all requests has the same structure:

{

  "Version": "string",

  "StatusCode": 0,

  "ErrorMessage": "string",

  "Results": {}

}

This structure is intended to immediately remove the complexity from http clients, which now have a single structure for returning requests.

Detailing the properties of the return object:

• Version: Displays the version of the Web API invoked;
• StatusCode: This property sends the HTTP Status Code of the response;
• ErrorMessage: In the event of an error, it displays the corresponding message;
• Results: Object with the content of the return. This object will always be a dictionary, whose key will be a string (which corresponds to the name of the return entity) and a return object.
  • The entities that are passed as ref in the ERP API are now returned in this object;
  • In the case of business entity update methods, the updated entity is sent in this object, duly updated (with the number actually saved, for example).

HTTP Request of each Request

In version 2, we use 4 types of HTTP Request

• GET: used in methods that return data (generally Query methods);
• POST: used in methods that create/update business entities;
• PUT: used in methods that update attributes of business entities (example: UpdateAttributeValue);
• DELETE: used in methods that remove business entities.

Blocking simultaneous requests for the same context

The BlockMultipleRequestsPerContext setting (true by default) is available in the web.config file to block simultaneous requests to the same ERP engine.

The ERP engines are instantiated according to the token requested, and the correct separation of resources is guaranteed when properly instrumented with the session key.

When the session key is not used, errors can occur as shared resources are used simultaneously. This configuration prevents such errors.

For more information, please see the Architecture section of the Web API documentation.

Web API Documentation with Swagger

Version 2 also provides the Swagger tool as a mechanism for documenting and invoking the Web API.

Swagger's default address will be: http://localhost:2018/WebApi/swagger/ui/index

This will also become the entry page for the Web API when accessing http://localhost:2018/WebApi.

Find out more about using Swagger in the support article.