API versioning

[pcapriotti]

Implement API versioning system. See docs/legacy/developer/api-versioning.md for details.

Tracked by:

• https://wearezeta.atlassian.net/browse/FS-127 (federation API versioning)
• https://wearezeta.atlassian.net/browse/SQCORE-1209 (add versions to client API routing tables)
• https://wearezeta.atlassian.net/browse/FS-63 (version negotiation)

Checklist

• The PR Title explains the impact of the change.
• The PR description provides context as to why the change should occur and what the code contributes to that effect. This could also be a link to a JIRA ticket or a Github issue, if there is one.
• If this PR changes development workflow or dependencies, they have been A) automated and B) documented under docs/developer/. All efforts have been taken to minimize development setup breakage or slowdown for co-workers.
• If HTTP endpoint paths have been added or renamed, the endpoint / config-flag checklist (see Wire-employee only backend wiki page) has been followed.
• changelog.d contains the following bits of information (details):
  • A file with the changelog entry in one or more suitable sub-sections. The sub-sections are marked by directories inside changelog.d.
  • If new config options introduced: added usage description under docs/reference/config-options.md
  • If new config options introduced: recommended measures to be taken by on-premise instance operators.

[fisx]

I like the outcome of this process! I think it's both pragmatic and reasonably elegant. I have a few nit-picks, and haven't read enough of this PR to approve it, but I'm generally happy.

[fisx]

I hope this is a typo? :)

Suggested change

	`/assets/v3` has been replaced by `/access`.
	`/assets/v3` has been replaced by `/assets`.

Also, isn't that something that could have gone into a separate PR?

[pcapriotti]

It could've, but I thought it would be useful to start using the new system immediately. It's kind of like adding tests for X in the same PR where you implement X itself. In fact, it is a bit worrying that we are not making significant use of it for the federation API. I've played around with it in a branch, though, by making some random changes to the API, and it seemed to be working reasonably well there, too.

[fisx]

Suggested change

	should disable development versions (and not advertise them in `/api-version`).
	should disable development versions (and not advertise them in `/api-version`).
	On the other hand, production clients must disregard all development versions
	as unsupported.

This would be easier if development versions would not also be listed as versions. I'm actually in favor of this. I think it's a lot less error-prone.

[pcapriotti]

I went back and forth with this, and in the end I think I prefer the current system, because it places no burden on clients. Clients can just start using V2 now, without any special logic, and as long as we disable it in production, it won't affect anything.

Also, it makes it easier to test, because we only need to make sure that the backend has a development version enabled, and not that the client has turned out development API access as well.

But I can be convinced otherwise. This is not too problematic to change later on, anyway.

[pcapriotti]

I have added the following paragraph:

Similarly, clients that are meant for production use can decide to ignore
development versions on their backend. This is not strictly necessary, but it
can be used as a safeguard against mistakes in deployment.

[fisx]

I went back and forth with this, and in the end I think I prefer the current system, because it places no burden on clients. Clients can just start using V2 now, without any special logic, and as long as we disable it in production, it won't affect anything.

Also, it makes it easier to test, because we only need to make sure that the backend has a development version enabled, and not that the client has turned out development API access as well.

But I can be convinced otherwise. This is not too problematic to change later on, anyway.

I'm ok with everything except the last sentence. :) So, yes, do it your way.