Projects:Retail API/Specs
 | Back to Projects:Retail_API |
Contents |
Goal
The main objective of this project is to provide a business oriented Retail API that allows external systems to interchange (import and export) information with Openbravo.
Functional Requirements
The functional requirement of this project is to provide an API that allows to import and export information of different Openbravo entities.
These entities will not be exactly the DAL Openbravo entities but rich entities that will put together information coming from different sources to generate its own definition. The definition of all these Retail API entities is summarized here.
To make use of this API different web services should be available:
- Export Service: a synchronous service that will allow to retrieve the information for each Retail API entity. It will be possible to specify a filter in the call for this service in order to select a particular subset of elements.
- Import Service: an asynchronous service that will allow to import elements of a Retail API entity. It will be asynchronous because it will not wait until all the elements are imported to return a result. Instead, it will directly return a reference to a job that will be in charge of importing the elements.
- Status Service: a service that will allow to check the status of a job in charge of importing elements.
The Web Services will be designed following the standard JSON API specification.
Technical Specs
Mappings Infrastructure
The different Retail API entities will be defined using the Application Dictionary, more specifically they will be defined using the External Integration Infrastructure. Thus, using the Entity Mapping window, it will be possible to define the different entities with their properties.
The representation of the Retail API (type of data) will be done using JSON objects.
Besides, a couple of new tabs will be added in the Entity Mapping window. They will help to define the different filters for the export entities.
With this approach, it will be possible to extend the entities and the export filters and to export the changes into custom modules.
Export Engine
As stated in the previous section, the export service will be a synchronous service. For this reason the Retail API will have an export engine based in the External Integration Export Infrastructure that will allow to map a set of IDs into the JSON representation of the Retail API objects in a synchronous way.
Import Engine
For the import flow, we will directly make use of the standard JSON EDL Import Process of the External Integration Infrastructure.
Thus, the import web service will return the ID of the EDL request in charge of processing the import asynchronously. With this ID and using the Status Service, it will be possible to check the status of the import processing.
Documentation
The specification of the import and export web services should be exposed using Swagger UI.
An ant base task will be created to automatically generate the Open API specification of both services at compile time, using the Application Dictionary definition of the different Retail API entities.