Service Versioning

Continuous Improvement

We are continuously working on improving the answers you get to your service requests you send. The efforts are split into the two main fields:

1. Data Research
2. Programming

Types of Changes

This progress results in three kinds of changes:

1. Changes behind the scenes.
   The API remains unchanged. No break, no new features. But internally, the server software works a bit differently, or uses new data bases, with improved name knowledge. Although the API is the same, some results will differ. 
   Such changes can happen any time, and are usually written about on the blog.
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 wsdl directly, then your code still works if it is tolerant in regard to additional output values - which it should be.
   Such changes happen infrequently.
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.

For you the user, it's a terrible thing when your existing program suddenly stops working. That's why, besides service availability, it is one of our main concerns to keep your application up and running.

Version Number in URL

We do this using a version number in the web service url. When introducing a new version number, older URLs remain functional for a defined amount of time.

Example url: api.nameapi.org/soap/v4.0/system/pinger?wsdl

4 is the major version, 0 is the minor version. Changes of type one do not have any impact on the url. Changes of type two make us publish a new api where the minor version is increased by one in the url.

Example url: api.nameapi.org/soap/v4.1/system/pinger?wsdl

For changes of type 3 we publish a new major version, for example v5.0. 

Where to select the Version

When you're speaking to wsdl directly, you set it in the url. 

If you're using one of our client libraries, then you just select the version of the client library that matches what you want, and don't worry about the url.

Change Management

We are aware that every change is a risk for our users, and apply them carefully.