Versioning of status endpoint format

[nichtich]

2. How do we deal with versioning?

While I think it would probably be best to introduce proper API versioning to jskos-server (and therefore to wikidata-jskos as well), it would probably be easier to just add the old config keys to the expanded status response, inferred from the new config format. Of course that would bloat the status response, but if we introduced some way of versioning for the API, the "default" version would still need to be the current one because we can't rewrite old clients, so consuming the API from the browser for example would still return the old responses.

Also, we couldn't really do versioning in the URI because that would break all our mapping and annotation URIs, and using a header would not be accessible via a browser request. I don't think there is a good solution, only different compromises.

Originally posted by @stefandesu in https://github.com/gbv/jskos-server/issues/69#issuecomment-521542609

[nichtich]

Fur current changes (#69):

• [x] keep old sets of fields (e.g. auth.identityProviders) in addition to the new fields
• [ ] change clients
• [x] remove old fields afterwards

For future versioning:

• [x] add version field with a semantic version number that refers to the API format (we can start with 1.0.0 after this refactoring)
• [x] create a JSON schema for the status format to better detect changes. The version number would basically refer to the schema -> #74
• [x] add check function to clients, so for instance Cocoda can detect when connecting to a jskos-server instance with incompatible version number -> implemented in branch in Cocoda, will be merged for 1.1.0 (https://github.com/gbv/cocoda/issues/461)

[stefandesu]

• remove old fields afterwards

This will still break older Cocoda versions in our archive, as I've noted in the original comment in #69. I mean there are other older versions that don't work anymore, but I'm not sure what the point of that archive is if older version aren't working anymore.

• add check function to clients, so for instance Cocoda can detect when connecting to a jskos-server instance with incompatible version number

What will Cocoda do with that information, not use the API anymore? That would only be a minor improvement over just having it break, to be honest.

In general: You are suggesting that we add the version as a field to the status response, right? But without allowing access to older API versions? In that case, I'd rather return the API version in the response header like described here.

[stefandesu]

Some more interesting links about API versioning that I've read earlier:

• https://www.mnot.net/blog/2012/07/11/header_versioning
• rest - Best practices for API versioning? - Stack Overflow
• GitHub API v3 | GitHub Developer Guide
• REST API Versioning Guide – REST API Tutorial

There are many different ways and opinions about this, and there's no right or wrong way I think (although some ways are objectively better than others I guess).

[stefandesu]

Implemented via 678d0a34fdc417b7bd144e9bc878961f4ca8dec4 (the issue tags got eaten because I had them on a separate line which was of course interpreted as a comment 🤦‍♂️).

[stefandesu]

• create a JSON schema for the status format to better detect changes. The version number would basically refer to the schema

Where should we put the JSON schema? And where should it be used? We could definitely use it in tests, so maybe it would make sense to have it in this repository as well.