MSC2475: API versioning

[turt2live]

Rendered

[richvdh]

I'm still a bit unclear about what you're proposing here.

I think you're saying that #2438 (comment) is wrong (which I agree with: we should be using v1 there)?

some examples would help.

[turt2live]

I'm not saying anything is wrong per-say, just that we need to figure this out.

[uhoreg]

Suggested change

	accetable to use a higher version when making large/sweeping changes to the API. For example,
	acceptable to use a higher version when making large/sweeping changes to the API. For example,

[uhoreg]

Suggested change

	for clarity and consistency with the bumps to the other endpoints.
	for clarity and consistency with the bumps to the other endpoints (`/v3/profile/`, `/v3/get_event/`, and `/v3/send_message`).

[richvdh]

proposal as it stands sgtm. the numbering on the examples needs fixing.

[turt2live]

gah, I put extra lines between the examples to avoid exactly that problem. Will give them titles I guess.

[anoadragon453]

@turt2live You could also do:

1. The spec currently has /v1/profile, /v1/get_event, and /v2/send_message.
   • An MSC to add a new endpoint, /delete_message is made. It would be /v1/delete_message because it's the first time we've seen it.

...perhaps.

Either way, this MSC looks pretty sane to me and @richvdh has agreed to it as well, so:

@mscbot fcp merge

[mscbot]

This FCP proposal has been cancelled by #2475 (comment).

Team member @mscbot has proposed to merge this. The next step is review by the rest of the tagged people:

• @dbkr
• @uhoreg
• @turt2live
• @ara4n
• @anoadragon453
• @richvdh
• @erikjohnston
• @KitsuneRal

Concerns:

• Needs more thinking time before we rush into things

Once at least 75% of reviewers approve (and there are no outstanding concerns), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for information about what commands tagged team members can give me.

[turt2live]

... I'm not yet convinced myself that the MSC is the way to go, and I see no reason to rush this through.

@mscbot concern Needs more thinking time before we rush into things

[deepbluev7]

I think something like this is sorely needed, especially if something like login should ever move to interactive auth and hashed passwords. I'm not sure, if I understand correctly, how this should work though:

• Does this mean an endpoint like /_matrix/client/r0/login becomes /_matrix/client/r0/v2/login?
• What about nested endpoints? /_matrix/client/r0/v2/user/{userId}/rooms/{roomId}/tags or /_matrix/client/r0/user/{userId}/rooms/{roomId}/v2/tags?
• what about conflicts, like you can't add a v2 here: /_matrix/client/r0/user/{userId}/rooms/{roomId}/tags/v2/{tag}, so maybe it only makes sense to add the v2 at the top level?

It seems like the federation API always adds the version below the top level, i.e. after /_matrix/federation/ or /_matrix/keys/, so maybe that was intended here? Would it be added after the r0 or before it though for the client server API?

Maybe tangentially related, is there some material for why the rX and vX versioning was chosen to be the way it currently is? I think I remember, that there was a longer discussion mentioned in a discussion about this topic.

[turt2live]

This doesn't touch the client-server API at all, and does not suggest moving the version number to anywhere except after the coarse scoping done by the path (/_matrix/:api/:version/:subpath).

Maybe tangentially related, is there some material for why the rX and vX versioning was chosen to be the way it currently is? I think I remember, that there was a longer discussion mentioned in a discussion about this topic.

It's old enough that any documentation has been lost to the wind. There might be some contained in this repo somewhere, but ultimately it's stuck in people's memories and not on paper. Some of those people no longer work on the project, unfortunately.

[ara4n]

From memory, the rationale for the /rX.Y.Z prefix in the CS API was:

• You don't have to guess what versions of APIs work together. There's one global prefix for the whole CS API, rather than the weird mix of /v1 and /v2_alpha prefixes we had before.
• It's tied to the released version of the spec, with the compatibility guarantees given by the X.Y.Z numbering scheme.

The disadvantage is that if some random minor API makes a backwards-incompatible change, in theory the entire prefix should change to be /r2 or /r3 or whatever - which some might see as cumbersome. Others might argue that this is a good reason to avoid backwards-incompatible changes wherever possible (as indeed we have so far, hence being on /r0.y.z still).

The other disadvantage is that the SS API never moved to use the /rX.Y.Z format, so we're currently very inconsistent between the APIs.

[deepbluev7]

@ara4n Thank you for the context. Those are just the problems with versioning in general. I think choosing the right tradeoff is really hard and there seems to be no perfect solution. I think it would make sense to accumulate /v2, /v3 changes and once they are stabilized, cut a new major revision, which removes old versions of those endpoints and puts them all under a global /r1, /r2 or whatever, so that a new server only needs to implement the /r1 API.

@turt2live So this proposal is only for the SS API? Was that not mentioned in the MSC or did I just miss it?

In any case, I think something like this is really needed for the CS API, but it needs a bit more work to fit there too and to specify the transition from /r0/v5 to /r1/v0 or /r1 (no suffix). There are a few endpoints in the CS API, that probably need a new version to improve them, but where you don't want to bump the full API version for now (like login for example). Similarly I'd say it would make sense to transition the federation API to /r0 at some point, when some of the /v1 endpoints should get dropped, to make implementing new homeservers easier.

[turt2live]

This affects all the APIs except the client-server API, as mentioned in the introduction. Making this affect client-server is best left for a different MSC.

[deepbluev7]

Thanks, I think that wasn't explicit enough for me :D

[turt2live]

@mscbot fcp cancel

This needs to be reviewed for accuracy and relevance (by me).

[turt2live]

This MSC is no longer relevant.