This module provides the Openbravo Retail API. It contains the definition of the different Retail API entities and exposes web services to import and export the information.
Retail API Entity Mapping
The definition of the standard Retail API entities is present in the Entity Mapping window. These definitions can be modified and/or extended with custom modules as any other entity mapping definition.
The export mappings (From Openbravo to External System integration direction) allows to define export filters which can be created under the Export Filters subtab.
Each of the records present in this tab will result in a new filter of the entity export endpoint. In addition, a default filter "byID" is automatically added for each export entity. Note that the definition of the byID filter is not displayed in this tab.
The export filters require the following information:
- Name: the filter name (byID name can not be used as it is reserved)
- HQL Where Clause: a where clause to be applied on the main entity (Mapped Entity). It supports using parameters with the standard parameter notation (using :).
- Description: metadata information which is included in the Open API specification.
- Return Multiple Results: it should be marked if after applying the filter multiple results can be returned. If just a single element is returned by the filter do not check this field.
If an export filter uses parameters, the metadata information of each parameters should be added in the Export Filter Parameters tab:
- Name: the parameter name
- Type: the parameter type
- Description: the parameter description
- Example: one of the possible values that the parameter can take
Retail API Web Services
The Retail API module provides a set of
Open API Specification
The specification of the Retail API Web Services can be seen and tested with this live environment.
Status Web Service
The import of elements through any of the available Retail API import web services is done in an asynchronous way using EDL. This web services usually return the ID of the EDL request in charge of the import task.
The Status Web Service allows to check the status of that kind of EDL requests in order to know whether the import process has (successfully) ended or not. This service can be invoked through a GET request to the following URL:
Updating the Open API Specification
If any of the Retail API entities is modified or a new export filter is added, the Open API specification of the web services should be updated accordingly.
To help with this task the Retail API module provides an ant task called generate.doc. This task should be invoked inside the Retail API module as follows:
Once this tasks is completed the Open API specification file (org.openbravo.retail.api-RetailAPI.json) will be updated.
Deploying the Retail API
To deploy and visualize the Retail API with Swagger UI, the steps described here needs to be followed.
Process to change the Retail API
The main goal of this project is to provide a business, functionally-relevant webservice-based API that customers can use to integrate their systems with Openbravo.
In order to achieve this goal, the API should remain reasonably stable over different releases so that customers can update Openbravo without fear of breaking their integrations.
That said, sometimes it is unavoidable to make changes. The way these changes should happen is the following:
- First, changes should be anticipated by the developer that is doing them. However, if not, automated tests will detect most cases anyway.
- Secondly, depending on the kind of change, different actions should take place:
- If changes consist in just adding new properties to an exporting entity, they should be documented in the API changes documentation.
- If changes consist in a fundamental modification of an structural part of an exporting entity (like removal of properties, or change of the data type of a property, or changing a one-to-many relationship into one-on-one), then an API change issue should be reported and approved by Product Organisation. If finally approved, the API changes documentation should be updated to include this changed.
- If changes consist on an addition of a new, non-mandatory property in an importing entity, then these changes should be documented in the API changes documentation.
- If changes consist either on a fundamental modification of a structural part of an importing entity, or an addition of a mandatory new property to an importing entity, an API change issue should be reported and approved. If finally approved, the API changes documentation should be updated.
The API changes documentation can be found here.