How to manage ascending compatibility for JSON formats in BusinessWorks and BusinessWorks Container Edition
In the digital world this is quiet often that the data structures exchanged between client and back-end applications need to be updated to manage new features required by the business. For the Integration layer this can be challenging to manage such frequent changes in large environments where you have multiple channels, geographies and back-end systems.
This is one of the reason of the popularity of the JSON data format in such context while it is more flexible than the XML data format.
BusinessWorks supports the JSON format and since release 6.6 allows to manage ascending compatibility for this format.
This article aims to explain how to manage ascending compatibility with JSON formats in BusinessWorks.
Context of a REST/JSON API defined by a swagger file
In such context:
. Client applications call Server applications
. The REST API is defined by a Swagger or Open API specification
. The Swagger defines the HTTP methods that are used and the request and response JSON message formats
Example of a swagger file:
Using the elements from this article it is possible to add fields or sub-structures in the ‘CustomerDetails’ definition without breaking existing applications that don’t use the new fields.
# Case 1 — Adding fields in the request message
In this case new fields need to be added in the request sent by one of the client applications to one or multiple server applications, the structure of the request message defined in the swagger file have to be updated with the following rules:
. Add the new fields or sub-structures
. Keep mandatory fields
. Optionally remove optional fields (this is to be done with care while they might be used by some applications)
In the BusinessWorks server application you just need to check the following option in the Request section of the REST binding configuration:
This is a good practice to check this option by default.
# Case 2 — Adding fields in the response message
In this case new fields need to be added in the response sent by one of the server applications to one or multiple client applications, the structure of the response message defined in the swagger file have to be updated with the following rules:
. Add the new fields or sub-structures
. Keep mandatory fields
. Optionally remove optional fields (this is to be done with care while they might be used by some applications)
In the BusinessWorks client application you just need to check the following option in the Response section of the REST binding configuration:
This is a good practice to check this option by default.
Note that the option is available only if the response format is set to JSON :
Context of the parsing of a JSON message
In this case new fields need to be added in a JSON message sent to a number of applications, but not all consumer applications are using the new fields.
The structure of the message have to be updated with the following rules:
. Add the new fields or sub-structures
. Keep mandatory fields
. Optionally remove optional fields (this is to be done with care while they might be used by some applications)
In the BusinessWorks application that don’t use the new fields you just need to check the following option in the Parse JSON activity (this option is available since BusinessWorks 6.6.1):
This is generally a good practice to check this option by default.
Summary
As we have seen in this article BusinessWorks and BusinessWorks Container Edition can manage ascending compatibility for messages in JSON formats.
