Negotiating API versions

[gitonthescene]

It looks like the API version here doesn't change much, but I'm not clear what the semantics are when the API does change. As mentioned here the service manifest includes a list of versions the server can support, but it's not clear what that means.

Is the client expected, to pick from among those versions? Does the client fail when it can't support any of those versions? If the server supports multiple versions, how does the client communicate that to the server? What exactly is the handshake mechanism?

Again, this doesn't seem urgent as the API version doesn't change much but having a well defined plan could help in figuring out what risks there are to a given change and mapping out a rollout of added features.

[wetneb]

My expectation is that most services will stick to one version of the specs, and then it is up to the client to adapt to the announced version. It would indeed fail if it does not support that version.

If two versions of the spec do not have breaking changes then it might be tempting for a server to support both at the same time, and then the client could follow either specs to issue their requests.

I am not sure what a "handshake mechanism" would look like in this context - maybe it would be interesting to look at examples from other protocols?

[gitonthescene]

If the services are to stick to one version, why would they supply a list of versions in the spec?

If there hasn’t been a plan for how version updates are to be handled then it might be best to try to make up some examples of typical scenarios. Do we know who the stakeholders are for this API?

My overall impression is that most of the meta information passed between the client and server is done through the service manifest request.

I suppose the client could pass the API version it’s using in every subsequent request. Then the server can declare what it can handle with the service manifest and know which version it’s dealing with on subsequent requests. It could refuse requests coming with an API version it’s unfamiliar with.

Ideally this would all be spelled out in the spec. The looser the spec the harder it is to plan changes.

[wetneb]

If the services are to stick to one version, why would they supply a list of versions in the spec?

Well, as I wrote above, they do not have to stick to one version. I have the feeling we are talking across here - can we keep the discussion constructive please?

About adding versioning information to individual requests: why not!

[gitonthescene]

I don’t follow. I’m trying to be constructive. I’ve even spelled out how a scenario could work. It might be more constructive to speak to that.

I’m not clear though on how you picture things working. Assuming most will stick to one version but leaving open the option to indicate a possibility to support multiple versions doesn’t paint a very clear picture. I think a spec should aim at painting a clear picture of what the expectations are.

I do agree the tone of this conversation is starting to feel contentious and I’m not sure why. I am feeling less inclined to contribute though.

[wetneb]

Maybe the misunderstanding was that by writing "My expectation is that most services will stick to one version of the specs, and then it is up to the client to adapt to the announced version", I was expressing my own, personal expectation about how the specs are going to be used. That does not mean I would want to enforce it in any way in the specs: I think it is nice if endpoints spend some effort making sure they are compatible with more versions. For instance, many endpoints support both CORS and JSONP, which are required by different versions of the specs. Does that help at all?

Maybe you could also help me better understand what sort of answer you were expecting to your question "Do we know who the stakeholders are for this API?", which confused me a little. We have the W3C Community Group, that you are part of - is that not a group of stakeholders?

[wetneb]

I can try to describe further how I understand the current specs:

As a service

I announce one or more versions of the specs I am compatible with in my manifest. I accept requests formatted according to any of the specs I support. I return responses complying with all of the specs I support.

As a client

I support one or more versions of the specs. When trying to use a reconciliation service, I check the versions it supports in its manifest. If it does not support any of the versions I support, then I cannot use this service. Otherwise I pick some version of the protocol and send requests to the service using this version.

Rationale

As a service implementer, supporting multiple versions is doable as long as the versions do not differ by incompatible changes, such as changing the meaning of a parameter. For instance, in many places our JSON schemas do not forbid adding other fields to JSON payloads.

Adding version information to individual requests does sound interesting as it would make it possible for a service to support more widely differing specs.

Are we on the same page here?

[wetneb]

Ah apologies @gitonthescene, I thought you were part of the community group already but it looks like you are not! Sorry for the confusion. Then, this is the group I was talking about: https://www.w3.org/community/reconciliation/

[tfmorris]

This seems to have stalled. I agree that compatibility considerations are important and that the spec should document expected behavior for both ends. Requiring clients to recognize a newly implemented version specification doesn't really work because you can't retroactively change clients which are already out in the field.

Versioning requests, with a fallback for unversioned requests, would at least allow a service to recognize that a client was speaking a version of the protocol which they are unwilling to support.

Also, the current versioning scheme assumes JSON serialization, but there may be a desire to change this in the future, so having the API URL itself versioned may be wise ie add a /v1/ term into the address which can be changed if you switch to completely incompatible protocol.

[gitonthescene]

I was mostly advocating for clarity above and not a specific proposal but this makes sense to me. It might be good to spell out the response to a request from a client with an unexpected version. I would think servers have the option of treating an unspecified version as being an incompatible version.

I like the idea of having the version in the URL too with the server having the option to route unspecified versions to a versioned API.