Comment 6 for bug 1393952

> Our specific motivation for this feature request was that the
> openstack-installer requires maas 1.7+, because it now uses the 1.7
> version of the boot-images import API calls that changed between 1.5 &
> 1.7.
>
> However, those changes seem more like a rework of an existing
> 'capability', the capability to trigger an import… Is the plan to
> capture any such externally visible change as a new 'capability'?

That particular change should have been signalled by a bump in the API
version. Unfortunately that wasn't possible, but I can't remember what
the problem was, though I think it was an issue with support from the
underlying library.

The web API is versioned as a whole. We could bump the API version
during development for each release as a matter of course. If nothing
significant changes we can fold the new version away just before release
time. This would get us accustomed to working with multiple API versions
even if we end up only exposing a single API version over multiple
releases.

Now, how we signal that a new API version is available I'm not sure.
Clients could sniff what versions are available by fetching the
capabilities views for the versions they have been written for.

> I note that the capabilities currently listed on e.g. [1] are much
> higher-level than that.

I think it's fine to advertise low-level, high-level, small, and big
things via capabilities. Unfortunately this overlaps with API versions.
Maybe API versions should be reserved for framework-like changes rather
than semantic changes?

Ach, it's a minefield. I'm not a fan of whole-API versioning. I'd rather
have capabilities like "boot-images-v1" and "boot-images-v2" to indicate
what APIs are available.