Agreed with Martin, to a large extent. You could do /.well-known/foo/v1, but of course you could also just call it something else, e.g., /.well-known/bar. The point being that if there's backwards-incompatible change in the semantics, it really is another thing. And of course ../v1.0 doesn't make any kind of sense, because minor versions are supposed to signify backwards-compatible changes, but by changing the URL, they become incompatible. More about this at <https://www.mnot.net/blog/2012/12/04/api-evolution>. One of the things on my list is to write something explaining how to use OpenAPI for standards; it's designed more for single-deployment APIs (see <https://www.mnot.net/blog/2012/06/25/http_api_complexity_model>), not ones that have multiple, uncoordinated deployments, so there are some foot guns there. Cheers, > On 25 Feb 2019, at 7:12 am, Martin Thomson <mt@xxxxxxxxxxxxxx> wrote: > > Michael, > > My view on this, which- in the interest of transparency - is not uniformly held, is that versioning in URLs is generally not advisable for the same reason x- isn't. See rfc 6648. > > I see /api/v1 all the time, but don't see the point. What that does is bake semantics into the path, which is akin to an rfc 7320 violation. > > The goal is to ensure that incompatible versions are properly distinguished. For that purpose, all you need to do is ensure that the URL for v1 is not the same as the URL for v2. To that end, /api and /apiv2 work amply. Or you could name the protocol. > > For est, I tend to think that /.well-known/ is overused in general, because configuring a URL is usually adequate. But I can't hold a strong position on a protocol that I barely know. Adding /est2 might be an answer if backwards compatibility would be problematic. It is also possible to use other ways to extend the protocol that are less violent. > > On Mon, Feb 25, 2019, at 04:55, Michael Richardson wrote: >> >> I'm not sure where this query goes, so ietf@xxxxxxxx. >> >> Outside of the IETF there seems to be a good tradition of versioning RESTful >> APIs using URLs like /api/v1.0.0 or such. >> >> The OpenAPI specification is promoted by Swagger.IO. >> (It does not appear to have been endorsed by any SDO-like entity) >> These APIs are typically versioned like: >> /vendor/version/endpoint >> >> The question is, how would one combine this into a /.well-known endpoint? >> It seems that originally /.well-known was intended to be for things that >> might be *combined* with other operator-controlled content. >> Really good example is robots.txt, webfinger, acme-challenge. >> /.well-known/core is about discoverying other things. >> >> RFC7030 established /.well-known/est, and it is being extended by the ANIMA >> WG in a number of documents. It's not clear to me that this ever belonged >> in /.well-known, as the service in question is very much dedicated to the >> being a Registrar. >> >> In particular, it seems a bit awkward to build versioned APIs that live >> in /.well-known. Not impossible, it just feels wrong. >> >> >> >> Some references/readings: >> https://www.predic8.de/rest-api-versioning.htm >> https://www.baeldung.com/rest-versioning >> https://restfulapi.net/versioning/ >> https://swagger.io/docs/specification/about/ >> >> >> -- >> Michael Richardson <mcr+IETF@xxxxxxxxxxxx>, Sandelman Software Works >> -= IPv6 IoT consulting =- >> >> >> >> >> Attachments: >> * signature.asc > -- Mark Nottingham https://www.mnot.net/
