Open Stack

I have some concerns about the /capabilities approach based on what we are
currently doing with extensions. I think these also apply to a "constructible"
api where features can be turned on and off at will.

I'm going to isolate this discussion to what is exposed within a specific
version of a service. I think the document already has a sane approach
for multiple versions. It is feature discovery within a single version
when parts of the api are optional that i am concerned with (whether or
not the optional parts are extensions or optional features).

Basically our goal is to provide a way for clients to determine what actions
are available on a server. Essentially this means a few things:

A) what resources are available
B) what actions can be performed on those resources
C) what (url) parameters are available?
D) what is the structure of the request/response?

HATEOS seems to provide the cleanest solution for A)

One advantage of the /extensions resource is that it (theoretically) could
provide a link to a wsdl (or jsonschema) providing information on how to interact
with the additional features it provides.

So we could replicate this functionality into capabilities but it seems like
it makes more sense for each resource to provide its own description.

Ideally i could do an OPTIONS /servers and get a response telling me the actions
it supports directly (including links to jsonschema or wsdl for each action). This
would take care of B and the linked schema documentation could provide D. We could
even include information about C in this document.

For client development seems like a much better solution than trying to encode
all of these changes into extension descriptors and having special logic in the
clients based on the existence of the extension.

Unfortunately I'm not sure if it solves the UI and UX (read Horizon) use case.
From a user experience perspective, big chunks of functionality need to be
turned on and off based on the existence of features/extensions. If i have a
broad feature that adds new paths and changes parameters/responses to existing
paths it might be useful to have a way to determine if that functionality exists
all at once without having to directly query each url to find if it suports part
of the functionality.

For this reason having a simple /capabilities (or maybe /features) makes sense.
I don't know that encoding the wsdl/jsonschema (as we currently do with extensions)
is useful. It would be nice to know that (for example) the os-start-stop extension
adds servers/<uuid>/start and servers/<uuid>/stop to a server resource or that the
OS-EXT-SRV-ATTR adds extra data to the servers/<uuid> response, but I'm not sure
there is a good way to encode that information into a structured document.

It is relatively easy to include the info at servers/<uuid> however:
{
 "features": ["OS-EXT-SRV-ATTR", "os-start-stop"],
 "server": {
   "OS-EXT-SRV-ATTR:host": "1169a68456af48238da47b1d5957a714",
   "OS-EXT-SRV-ATTR:hypervisor_hostname": "fake-mini",
   "OS-EXT-SRV-ATTR:instance_name": "instance-00000001",
   "links": [ 
     {"rel": "self",
      "href":"http://example.org/v3/servers/009e9aca-b765-11e2-855a-008cfa10b980"},
     {"rel": "start",
      "href":"http://example.org/v3/servers/009e9aca-b765-11e2-855a-008cfa10b980/start"
      "feature": "os-start-stop"},
     {"rel": "stop",
      "href":"http://example.org/v3/servers/009e9aca-b765-11e2-855a-008cfa10b980/stop"
      "feature": "os-start-stop"}.
   ]
  }
}

or we could just stick the "feature/capability" info as metadata in the OPTIONS response.

Which brings up the idea that /capabilities might be better organized restfully where we have a list at capabilities and detail at /capabilities/<name>
/capabilities/os-start-stop
/capabilities/OS-EXT-SRV-ATTR

This would allow the references above to be hrefs:
"feature": "http://example.org/v3/capabilities/os-start-stop"

Vish


On May 1, 2013, at 5:46 PM, Gabriel Hurley <Gabriel.Hurley at nebula.com> wrote:

> Based on input from several of the PTLs (and others), I'd like to propose the following outline for how version discovery should be handled across heterogeneous clouds:
> 
> https://etherpad.openstack.org/api-version-discovery-proposal
> 
> Further discussion is absolutely welcome, and I would like to propose it as a topic for review by the Technical Committee at the next meeting since it involves a significant cross-project standardization effort.
> 
> All the best,
> 
>    - Gabriel
> 
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev