12.1. Mapping-API

Based on the article ‘Mapping van AFD 1.0 naar AFD 2.0 geautomatiseerd’ (in SIVI AFS Magazine May 2022).

Mapping-API for all mappings related to SIVI AFS

SIVI offers an API to provide mappings from one data catalog to another. More specific, the API converts a message from one data standard to another data standard, for example from AFD 1.0 to AFD 2.0. More information (in Dutch), as well as an overview of currently available mappings, can be found on the SIVI website about the mapping-API. The first mapping that the SIVI mapping-API supports, is the conversion from AFD 1.0 to AFD 2.0. In this mapping, an AFD 1.0 input in XML is converted to a corresponding AFD 2.0 output in JSON.

Mapping process

The messages are processed statelessly by the mapping-API and are not stored anywhere. This means: the mapping is executed in random-access memory and is no longer present after processing is completed. This prevents the data from being used in an improper way. Apart from that, SIVI does record process data about the use of the mapping-API:

• Requested type of mapping
• Version number of the mapping
• The applicant
• Size of the message
• Mapping throughput
• Successful completion of the mapping
  

If a mapping was not completed successfully then an error message is returned.

The process

An AFD 1.0 message in XML is converted to base64 in order to add it to the request. Default features are available in all common development environments.
If the message has been converted to base64, we can pass this along as the value of the ‘content’ attribute in an AFD 2.0 documentStructure. With the designation of the mapping in the commonFunctional we wish to perform, the message is ready for the call of the mappingService API.
When calling the mappingService, the indicated mapping (AFD 1.0 to AFD 2.0) is executed. After mapping the message, the API returns a similar JSON message in AFD 2.0 format with the translated message as content encoded to a base64 document. This reply message also contains the version number of the software used and the version of the mapping, in the commonTechnical entity.
Finally, the base64 document ‘content is decoded. This produces’(returns?) the AFD 2.0 JSON variant of the submitted AFD 1.0 XML message.

Fair use policy

SIVI uses a Fair Use Policy for the mappingService API. For very intensive and/or heavy use we need to make additional arrangements together. The default query limit is currently 40 API requests per minute and with a maximum message size of 2MB.

More information on the mapping-API, including a manual, terms of use and an application form, is available on the website of SIVI (in Dutch).