Open Stack

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"
  }
}

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130509/cedc53f7/attachment.html>