Minimal client API versioning

[pcapriotti]

This PR implements the bare minimum interface for client API version negotiation.

The changes in the nginz chart are based on https://github.com/zinfra/cailleach/pull/879 and result in the following diff.

Tracked by https://wearezeta.atlassian.net/browse/FS-440.

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 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 public end-points have been changed or added: does nginz need un upgrade?

[fisx]

it just occurred to me that the nginz changes are a lot or work but pretty straight-forward. just add a (/v(\d+))? in front of every path and make them all regexps. but everybody except me probably already thought of that. :) https://xkcd.com/564/

[pcapriotti]

it just occurred to me that the nginz changes are a lot or work but pretty straight-forward. just add a (/v(\d+))? in front of every path and make them all regexps. but everybody except me probably already thought of that. :) https://xkcd.com/564/

Yep, that's what I've been doing.

[fisx]

You should also have a flag in the server config(s) that keeps supported versions from being advertised, so we can allow on-prem backends to upgrade without forcing them to make their network infrastructure federation-ready:

  removeSupportedApiVersions:
  - 1

(not sure about the name)

[pcapriotti]

You should also have a flag in the server config(s) that keeps supported versions from being advertised, so we can allow on-prem backends to upgrade without forcing them to make their network infrastructure federation-ready:

I don't follow. Version 1 can be supported without having to enable federation or make any changes to the infrastructure. This change has not much to do with federation, really.

[fisx]

Why is this not in Wire.API.Routes.Version?

[pcapriotti]

VersionInfo is more general, and can be used for other API version lists, whereas Wire.API.Routes.Version is specific for the client API.

[fisx]

What about Version, then? Will there be a type Version for the federation server-to-server API as well?

[pcapriotti]

Yes, that was the idea, as well as for other APIs that need to be versioned separately.

[fisx]

qualify this, and call versionSwagger swaggerDoc?

[pcapriotti]

I don't like to create name clashes on purpose and resolve them with qualified imports. It makes everything more awkward and I don't see the benefit.

[fisx]

I won't insist, but I think we agreed at some point (we should document these things) that imports should either be explicit or qualified, but not neither. Doesn't have to happen now, since we're not consistent, but can you get on board with the general idea?

[pcapriotti]

Well, I disagree with the general idea, but if it's something everyone else agrees on, I'll comply.