MAAS does not advertise its capabilities

[Gavin Panella]

Clients of MAAS must sniff around to discover or infer what capabilities the MAAS they're talking to has. For example, support for VLANs. It would be useful if MAAS were to publish a list of its capabilities.

A simple implementation is all that's needed. For example, a /capabilities/ view would return a JSON list of capability names, e.g.:

    ["networks-vlan", "networks-lldp", ...]

This would remove the need for a global API version, which is unwieldy, and let us add and remove smaller chunks of API when it makes sense.

[Raphaël Badin (rvb)]

Instead of limiting the response to a list, I suggest we make room for providing other types of information in the future and return a dict: { 'capabilities': [...]}.

[Gavin Panella (allenap)]

My first instinct was YAGNI, but I guess it could be used for declaring deprecations, for example.

Or... we could have an "extended-capabilities" capability, implying there's a /capabilities/extended/ view ;-)

[Raphaël Badin (rvb)]

Having the 'revision' (as I suggested originally) could still be useful, even alongside the list of capabilities. For instance if a client has a problem with a particular bug, that you know has been fixed in a particular revision.

[Gavin Panella (allenap)]

On 26 March 2014 13:03, Raphaël Badin <email address hidden> wrote:
> I see the API versioning as something orthogonal to having the API
> declare its capabilities. It's meant to allow us to change the API in
> backward incompatible ways.

Using capabilities here would be better, I think. They'd allow us to
change the API as we like, bit by bit. For example, "networks-vlan"
could refer to the current implementation of VLANs in MAAS, and
"network-vlans-enhanced" could refer to a different implementation, with
different behaviour (e.g. SDN support) and mechanism (e.g. change of web
API framework).

Imagine we want to switch to a different web API framework, or change
the on-wire representation of objects in MAAS. With a global API version
we would either have to make everything work under the new framework at
once and make it available as 2.0, say, or figure out how to coordinate
with clients as to what's available in which API version at any moment
in time... which is akin to declaring capabilities. Why then bother with
the 2.0?

As I describe it, behaviour and mechanism are conflated. However, a
change to either is going to require a change in the client, and that's
the reason for declaring capabilities or having an API version anyway.

[Gavin Panella (allenap)]

> Having the 'revision' (as I suggested originally) could still be
> useful, even alongside the list of capabilities. For instance if a
> client has a problem with a particular bug, that you know has been
> fixed in a particular revision.

Okay. We could have a /version/ view like:

  {
    "version": "1.5",
    "revision": 1234,
    "capabilities": [...],
  }

?

[Raphaël Badin (rvb)]

On 03/26/2014 02:59 PM, Gavin Panella wrote:
> On 26 March 2014 13:03, Raphaël Badin <email address hidden> wrote:
>> I see the API versioning as something orthogonal to having the API
>> declare its capabilities. It's meant to allow us to change the API in
>> backward incompatible ways.
>
> Using capabilities here would be better, I think. They'd allow us to
> change the API as we like, bit by bit. For example, "networks-vlan"
> could refer to the current implementation of VLANs in MAAS, and
> "network-vlans-enhanced" could refer to a different implementation, with
> different behaviour (e.g. SDN support) and mechanism (e.g. change of web
> API framework).
>
> Imagine we want to switch to a different web API framework, or change
> the on-wire representation of objects in MAAS. With a global API version
> we would either have to make everything work under the new framework at
> once and make it available as 2.0, say, or figure out how to coordinate
> with clients as to what's available in which API version at any moment
> in time... which is akin to declaring capabilities. Why then bother with
> the 2.0?

This is precisely for this kind of big-bang change that I think API
versioning is much better suited. For instance, if we wanted to fix the
inconsistency that we have in the API where we use either 'read' or
'list' as the operation name to list objects in the API. We wouldn't
want to rename all the existing capabilities to *-enhanced. Moving to
API 2.0 would be much simpler.

[Raphaël Badin (rvb)]

On 03/26/2014 03:09 PM, Gavin Panella wrote:
>> Having the 'revision' (as I suggested originally) could still be
>> useful, even alongside the list of capabilities. For instance if a
>> client has a problem with a particular bug, that you know has been
>> fixed in a particular revision.
>
> Okay. We could have a /version/ view like:
>
> {
> "version": "1.5",
> "revision": 1234,
> "capabilities": [...],
> }
>
> ?

Sounds good to me.

[Raphaël Badin (rvb)]

On 03/26/2014 03:09 PM, Gavin Panella wrote:
>> Having the 'revision' (as I suggested originally) could still be
>> useful, even alongside the list of capabilities. For instance if a
>> client has a problem with a particular bug, that you know has been
>> fixed in a particular revision.
>
> Okay. We could have a /version/ view like:
>
> {
> "version": "1.5",
> "revision": 1234,
> "capabilities": [...],
> }

Now, we need to find names for the existing capabilities. And, as you
very well know, naming things is one of the two really hard things in
Computer Science ;).