It is our top priority to keep your integration functional. This document explains how the continuous efforts in improving the PII Platform affect the web service APIs.
Why It Matters
An integrated API that stops working causes business interruption. An API that requires modifications by the client causes cost and binds human resources. That’s why, besides service availability, it is one of our main concerns to keep your application up and running.
Continuous Improvement
Optimaize has teams persistently improving the inner workings of the PII Platform, to return more accurate results to API calls. The efforts are divided into the two main fields:
- Data development, Data Research
- Software development, Programming
This progress results in three kinds of changes.
Types of Changes
Type 1
Changes behind the scenes
The API remains unchanged. No break, no new features. But internally, the software works a bit differently, or uses extended dictionaries with improved name knowledge. Although the API is the same, some results will differ.
Such changes can happen at any time.
Type 2
API enhancements
The API offers new optional features, while still maintaining the same functionality as before. This can be: completely new additional web service types, additional input parameters, or additional information in the returned values, or additions to enumeration values. If you are using one of our client libraries, your code will still work. If you’re addressing the REST endpoints directly, then your code still works if it is tolerant in regard to additional output values – which it should be.
Such changes happen infrequently.
Type 3
Breaking changes
The API changes in a way that makes some of the requests that worked before not work anymore. The code for the affected requests needs to be adjusted for the new syntax. Examples are: a web service is renamed or removed, an input or output parameter is renamed or removed or the data type is changed.
Such changes happen rarely.
Version Number in URL
The version number is in the web service URL.
Example URL: https://api.example.org/rest/v5.3/system/ping
5 is the major version, 3 is the minor version. Changes of type one do not trigger a change in the URL. Changes of type two make us publish a new API where the minor version is increased by one.
Example URL: https://api.example.org/rest/v5.4/system/ping
For changes of type 3 we publish a new major version, while resetting the minor version to zero.
Example URL: https://api.example.org/rest/v6.0/system/ping
Where to select the Version
When you’re speaking to REST directly, you set it in the URL.
If you’re using one of our client libraries, then you have a version of the client library that matches the API version. You are still able to change the API version number in code using a variable, as the examples demonstrate.
Change Management
We are aware that every change is a risk for our users, and apply them carefully.
Changes are mentioned in release and deployment notes.
Data and software changes go through a lengthy testing process with thousands of test cases applied before being deployed to our cloud, or before making releases available to our customers.
Previous versions remain active
When introducing a new version number, older URLs remain functional. You may change the URL in your calls whenever you feel ready.
All services bump simultaneously
When publishing a new API version, all endpoints are available with the new version, even if nothing changed for one specific service. This way you do not have to guess which service is available under which version number. Generally you will call all endpoints using the same version.