- 10 Mar 2023
Backwards Compatibility API Usage
- Updated on 10 Mar 2023
In all examples, replace <myMaskingEngine> with the hostname or IP address of your virtual machine.
API Versioning Context
The Masking API is versioned in accordance with the Semantic Versioning format: http://semver.org/. When the Masking API is updated, a new API version will be released. Scripts must reference an explicit API version or else there are no guarantees that the scripts will work on future releases of the Masking API.
Pinning Down a Version Number To Guarantee Backwards-Compatibility
This is the format for specifying a version in the URL of an API request targeting the environments endpoints.
Specifying the version for endpoint guarantees that the requester receives a response containing all of the fields that were present in that version of the API. This is intended to allow scripts that specify a masking API version in the URL to continue working upon future upgrades of the Masking product--even if a newer version of the API is available in the future Masking product.
For example, consider the scenario where a script is being developed today with a pinned down version v5.0.0 in the URL of the API requests. Upon upgrade to a future release of the Masking product that has the API v5.1.0 available, the same, untouched script that was developed with the pinned down version v5.0.0 in the URL of the API requests are expected to continue working. That said, in order to leverage any new features of the API v5.1.0, the original script will need to be updated to specify the new API version in the URL, and the requests may need to be updated to conform to the new API specification.
While specifying a version for endpoint guarantees that all fields present in that version will be contained in the API response, it does not mean that new fields that have since been added to that endpoint in subsequent versions will be excluded. We, therefore, recommend that API users write their scripts to parse the JSON response objects by key name, rather than by key index, to prevent these additional fields from breaking any scripts.
Omitted Version Numbers
This is the format for not specifying a version in the URL of an API request targeting the environments endpoints. When the API version number is omitted, the latest API version is taken as a default. In the first 5.2 release, an API request with an omitted version number will be interpreted as a request against the v5.0.0 version of the API. In a future release that hypothetically has the API v5.3.0 available, an API request with an omitted version number will be interpreted as a request against the v5.3.0 version of the API.
Scripts that omit the version of the Masking API in the URL are not guaranteed to work upon future upgrades of the Masking product because the API specification may change between versions and requests that conform to the old API specification may not work on the new API specification.
If the version is omitted from the base path of the request's URL, but wishes to be treated using a specific masking API version that is not the latest version, set the DefaultApiVersion application setting. If the DefaultApiVersion is not set and the version is omitted from the URL, the latest version of the API on that engine will be used.