Open Stack

Totally in favor of the /capabilities/<version> suggestion. I've updated the etherpad to reflect that.

FWIW, I had originally misread your concern in the etherpad as the exact opposite and thought it was a non-issue, hence my clearing it out in the cleanup. Sorry about that. Duly fixed now.

All the best,

    - Gabriel

> -----Original Message-----
> From: John Dickinson [mailto:me at not.mn]
> Sent: Monday, May 20, 2013 10:18 AM
> To: OpenStack Development Mailing List
> Subject: Re: [openstack-dev] [openstack-tc] Proposal for API version
> discovery
> 
> As was mentioned on the etherpad (but since deleted), a
> /version/capabilities path for discoverability will not work for Swift. Using
> that pattern, "capabilities" could be a valid account in all existing clusters (eg
> http://swift/v1/capabilities/). The alternative proposed was for /version-
> capabilities. I'm also ok with a /capabilities/version pattern.
> 
> --John
> 
> 
> 
> 
> On May 14, 2013, at 12:31 PM, Gabriel Hurley <Gabriel.Hurley at nebula.com>
> wrote:
> 
> > It seems like there's some reasonable support for going in the direction of
> HATEOS-esque links for defining capabilities... I suppose it'd be nice to see
> one of the more extreme examples taken to its logical conclusion. Could
> someone more familiar with the breadth of Nova's extensions write out
> what it would look like if you actually provided links for every action
> reasonably available on a server?
> >
> > -          Gabriel
> >
> > From: Dolph Mathews [mailto:dolph.mathews at gmail.com]
> > Sent: Monday, May 13, 2013 9:26 AM
> > To: OpenStack Development Mailing List
> > Subject: Re: [openstack-dev] [openstack-tc] Proposal for API version
> > discovery
> >
> >
> > On Thu, May 9, 2013 at 8:40 AM, Mark Washenberger
> <mark.washenberger at markwash.net> wrote:
> > I'm not sure that is really 100% of the problem here, but we are definitely
> doing links in an inefficient way these days, due to an early misconception
> some of us on the Nova team had about *how* to do hyperlinks in json.
> >
> > Json schema [1] provides ways to indicate, _in the schema of an
> > object_, how it is linked to other objects. For example, if I had an
> > object
> >
> > GET /widgets/foo
> > {
> >   'name': 'foo',
> >   'self': '/widgets/foo',
> >   'bar': '/widgets/foobar',
> > }
> >
> > I might use a schema to communicate that 'self' is a self link, and
> > that 'bar' is a related resource by publishing a schema
> >
> > GET /schemas/object
> > {
> >    'type': 'object',
> >    'properties': {
> >       'name': {'type': 'string'},
> >       'self': {'type': 'string'},
> >       'bar': {'type': 'string'},
> >    },
> >    'links': [
> >       {'rel': 'self', 'href': '{self}'},
> >       {'rel': 'related', 'href': '{bar}'}
> >    ]
> > }
> >
> > What this schema says is that name, self, and bar are string types, that you
> can construct a self link using the value of the "self" property, and that you
> can construct a related link using the value of the "bar" property.
> >
> > For some reason I cannot remember, we neglected to realize that link
> descriptor objects [2] were only intended for json schema objects, not the
> regular objects described by the schemas. In the process, we made
> hyperlinks in our apis really inefficient by loading them up with unnecessary
> 'rels' and 'hrefs'. We also made finding relevant links difficult by requiring
> clients to iterate through an array rather than just explicitly looking up the
> relevant properties.
> >
> > Glance v2 api fixes this problem. But we also tried to go all-in on
> > being schema driven. This combined approach is fine for Glance, but
> > I'm not sure that the "schema-driven" part is necessarily that useful
> > for others. In any case, we needn't have such bloated json hyperlinks
> > for future openstack apis. For example, if you want to have actions
> > listed for a server, you could just do
> >
> > {
> >   "id": "abcd",
> >   ...
> >   "actions": {
> >     "stop": "/servers/abcd/stop",
> >     "snapshot": "/servers/abcd/snapshot"
> >   }
> > }
> >
> >
> > +1; identity api v3 addresses this as well, but uses a "links" container to
> avoid namespace pollution.
> >
> >   {
> >     "entity": {
> >       "id": string,
> >       "name": string
> >       "links": {
> >         "self": url,
> >         "related_collection": url
> >       }
> >     }
> >   }
> >
> > https://github.com/openstack/identity-api/blob/master/openstack-identi
> > ty-api/src/markdown/identity-api-v3.md#create-an-entity
> >
> >
> > which is a bit more compressed.
> >
> > [1] - http://tools.ietf.org/html/draft-zyp-json-schema-03
> > [2] - http://tools.ietf.org/html/draft-zyp-json-schema-03#section-6.1
> >
> >
> > On Wed, May 8, 2013 at 10:33 PM, Mark McLoughlin
> <markmc at redhat.com> wrote:
> > On Wed, 2013-05-08 at 18:59 +0000, Gabriel Hurley wrote:
> > > > -----Original Message-----
> > > > From: Vishvananda Ishaya [mailto:vishvananda at gmail.com]
> > > > Sent: Tuesday, May 07, 2013 3:44 PM
> > >
> > > > 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"}.
> > > >    ]
> > > >   }
> > > > }
> > >
> > > Tht perfectly illustrates my biggest concern with doing this on a
> > > per-resource basis.
> >
> > Per-resource does allow you to expose whether a user has permission to
> > perform an action, though.
> >
> > >  The list of "links" gets unconscionably enormous. If I do a "list"
> > > call and retrieve 100 instances each with 100 links because you have
> > > 20 extensions the whole thing becomes a mess. I think it's much more
> > > sane (though less explicit) to understand what's provided by the
> > > service and extrapolate that to the individual resources therein.
> >
> > Yeah, lots of links can be messy. How about URI templates?
> >
> > Maybe we have them as a /capabilities/templates resource:
> >
> >   {"templates": [
> >      {"rel": "server_start_action",
> >       "href": "http://example.org/v3/servers/{server_uuid}"
> >      }
> >   ]}
> >
> > then just do:
> >
> >   "links": [
> >     {"rel": "start", "template": "server_start_action"}
> >   ]
> >
> > Just a thought ...
> >
> > Cheers,
> > Mark.
> >
> >
> > _______________________________________________
> > OpenStack-TC mailing list
> > OpenStack-TC at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-tc
> >
> >
> > _______________________________________________
> > OpenStack-dev mailing list
> > OpenStack-dev at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
> >
> > _______________________________________________
> > OpenStack-dev mailing list
> > OpenStack-dev at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> 
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev