Mark Nottingham <mnot@xxxxxxxx> wrote:
> Agreed with Martin, to a large extent.
Good to know.
> 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.
> 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
> 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.
I found your blog posting made a good point. My experience is that people
have the experience of starting "One Client, One Server", and then they are
suddendly in Many Client,Many Server, either because the company was
restructured, or because they went "public". The Besos legend includes him
declaring that all APIs could be opened at any time, and people better be
ready. (Many have lamented that Google doesn't have the same approach)
--
] Never tell me the odds! | ipv6 mesh networks [
] Michael Richardson, Sandelman Software Works | IoT architect [
] mcr@xxxxxxxxxxxx http://www.sandelman.ca/ | ruby on rails [
--
Michael Richardson <mcr+IETF@xxxxxxxxxxxx>, Sandelman Software Works
-= IPv6 IoT consulting =-
Attachment:
signature.asc
Description: PGP signature
