feature req: api call to get current running version of maas

Very nice suggestion.

Maybe something like
{
  "version": "1.7.0",
  "revision": "3299"
}

We have the capabilities view [1][2] that's intended for this. Give us a list of those things you want to be conditional on and we can add them.

[1] MAAS 1.5: http://maas.ubuntu.com/docs1.5/capabilities.html
[2] MAAS 1.7: http://maas.ubuntu.com/docs1.7/capabilities.html

On Tuesday 18 Nov 2014 22:27:19 you wrote:
> We have the capabilities view [1][2] that's intended for this. Give us a
> list of those things you want to be conditional on and we can add them.
>
> [1] MAAS 1.5: http://maas.ubuntu.com/docs1.5/capabilities.html
> [2] MAAS 1.7: http://maas.ubuntu.com/docs1.7/capabilities.html

That doesn't answer the question of versions though, which may change when
capabilities do not. There may be some other semantic change which is
implicit in a version bump.

We can add the version/revision info in the capabilities structre easily
enough.

> That doesn't answer the question of versions though, which may change
> when capabilities do not. There may be some other semantic change
> which is implicit in a version bump.

Explicitly signalling semantic changes is what that view is meant for.
It was designed so that people would not use version numbers and not
come to depend on implicit behaviour changes.

Capabilities can be turned on and off. Version numbers can only move
forwards. There's no way to signal via a version number that something
that once was available is no longer available. Instead, all clients
must be updated.

> We can add the version/revision info in the capabilities structre
> easily enough.

Please see if you can avoid doing that.

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'?

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

[1]: http://maas.ubuntu.com/docs1.7/capabilities.html

On Tue, Nov 18, 2014 at 6:00 PM, Gavin Panella <email address hidden>
wrote:

> > That doesn't answer the question of versions though, which may change
> > when capabilities do not. There may be some other semantic change
> > which is implicit in a version bump.
>
> Explicitly signalling semantic changes is what that view is meant for.
> It was designed so that people would not use version numbers and not
> come to depend on implicit behaviour changes.
>
> Capabilities can be turned on and off. Version numbers can only move
> forwards. There's no way to signal via a version number that something
> that once was available is no longer available. Instead, all clients
> must be updated.
>
> > We can add the version/revision info in the capabilities structre
> > easily enough.
>
> Please see if you can avoid doing that.
>
> --
> You received this bug notification because you are a member of Solutions
> Engineering, which is subscribed to the bug report.
> https://bugs.launchpad.net/bugs/1393952
>
> Title:
> feature req: api call to get current running version of maas
>
> Status in MAAS:
> Triaged
>
> Bug description:
> In our unmanaged installer we'd like to only perform a deployment if
> existing MAAS version meets our requirements. We could easily pull
> this from MAAS if our installer is running on the same machine. In the
> cases where the unmanaged installer is on a separate machine we'd like
> to have a way to access the api to return a version string, or a hash
> map of various system/software specs related to MAAS.
>
> Something as simple as
>
> GET /api/maas_version
>
> { 'version' : '1.7.xxx' }
>
> Thanks!
>
> To manage notifications about this bug go to:
> https://bugs.launchpad.net/maas/+bug/1393952/+subscriptions
>

> 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.

On Wednesday 19 Nov 2014 00:00:40 you wrote:
> > That doesn't answer the question of versions though, which may change
> > when capabilities do not. There may be some other semantic change
> > which is implicit in a version bump.
>
> Explicitly signalling semantic changes is what that view is meant for.
> It was designed so that people would not use version numbers and not
> come to depend on implicit behaviour changes.
>
> Capabilities can be turned on and off. Version numbers can only move
> forwards. There's no way to signal via a version number that something
> that once was available is no longer available. Instead, all clients
> must be updated.
>
> > We can add the version/revision info in the capabilities structre
> > easily enough.
>
> Please see if you can avoid doing that.

Honestly, I can see the benefit of both approaches. If we provide both, is it
*that* bad? People using the API are not stupid and will understand that
looking at the capability is better, but on occasion the version will be more
useful.

On 11/19/14 19:55, Gavin Panella wrote:
> 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.

YES, yes yes. This is the one thing that Azure's API got right (one of
the fields to each request was a version).

I had another thought about this. It might be useful to have revision data
purely for the benefit of automating "maas refresh".