add versioning to API

[Robert Jäschke]

Problem: When we want/need to change the XML schema of the API XML, we have to ensure that all clients can understand the new schema. Adding attributes / nodes is probably no problem (until no client does schema validation) but removing/renaming breaks clients.

Proposed Solution: add a version number to the XML output and let clients check it. They can then inform the user, that they have to update the client.

The version number could have several parts, i.e.:

"2.1.4"

a change in the last part means, non-validating clients should not break, i.e., there has been nothing changed, only things added (meaning, clients just don't see the new things)

a change in the second part means, client needs to be updated.

or more complex scheme.

[Robert Jäschke]

In retrospect, we "survived" without this for quite some time. Hence, it doesn't seem to be sooo urgent.

[Daniel Zoller]

some links for reading:

• http://java.dzone.com/articles/your-api-versioning-wrong
• http://apiux.com/2013/05/14/api-versioning/

I would go with the media type solution (e.g GitHub also uses this for their api (https://developer.github.com/v3/versions/))