On Mon, Feb 25, 2019 at 10:51:55AM -0500, Michael Richardson wrote:
> Mark Nottingham <mnot@xxxxxxxx> wrote:
> > 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.
>
> Registering /.well-known/bar requires an IANA action, and pollutes that
> namespace, so it seems like a bad idea.
You could register /.well-known/foo and then have sub-endpoints there
with different names for different versions: /.well-known/foo/{bar, baz}.
> > 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>.
>
> I agree that semantic versioning in the URL seems dumb, because only the
> first digit should matter as far being compatible.
>
> I suppose using /api/1.0.1 and getting a 404 is a pretty clear statement that a
> minor change is not supported, but I don't really get it. So we agree on /v1
> vs /v2 makes more sense than 1.0.0 and 2.0.0
There can always be some other way to negotiate versions, like:
GET /.well-known/foo/versions
Or encode the versions into MIME types and use Accept/Content-Type for
version negotiation/indication.
Alternatively we could have a standard header for generic API version
negotiation/indication. Though Accept/Content-Type works for me.
For some applications this might make more sense because the URIs use
Accept/Content-Type to support both browser interfaces and API
interfaces, then URI portability between the two becomes desirable, and
so now you have URI local-part stability requirements that prevent you
from making backwards-incompatible changes to the API without some
header-based version negotiation.
> > 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.
>
> I would welcome a discussion about OpenAPI in IETF specifications.
> Mechanically, how to do it (throw the YAML in as a an appendix? Inline?
> Split up the YAML? Which text is normative...), and pieces of OpenAPI to
> avoid.
>
> My EST extension protocol is a bit complex from an OpenAPI point of
> view. First Alice talks to Bob, and get something, and gives it to Frank, and
> Frank then speaks to Joe, and returns something to Alice, which returns to
> Bob with it. OAUTH2 has a similar level of complexity. I don't see an
> obvious way in OpenAPI to express the coupling between API calls.
+1
Nico
--
