Open Stack

Hi Mark,

On Tue, 2011-10-25 at 15:20 +1100, Mark Nottingham wrote:
[snip]
> What do people think of the linked approach to versioning and extensibility?

I like it. With the exception of the media types, it's very similar to
the approach we took with the RHEV API[1] and it works really well. We
only postponed adding media types because they didn't add any immediate
benefit, but they are the Right Thing.

Just one small thing:

> GET / HTTP/1.1
> Host: api.example.com
> Accept: application/vnd.openstack-catalogue.json
> 
> getting back:
> 
> HTTP/1.1 200 OK
> Content-Type: application/vnd.openstack-catalogue.json
> {
>   "links": {
>     "openstack-server-list": "/servers/",
>     "openstack-server-detail": "/servers/{server_id}",
>     "openstack-images": "images/{image_id}",
>     "openstack-users": "users/{user_id}"
>   }
> }

Why are servers different images and users here? Is that just a typo and
you left out the "{server_id}"?

Thing is, I prefer it - IMHO, the catalogue should list collections and
individual items in the collection can be retrieved by querying the
collection. If a client has a entity ID, it should be able to use query
parameters to efficiently obtain it and then it can retain the URI for
future use.

I'm not so keen on requiring clients interpret URI templates in order to
navigate the top-level catalogue. There just isn't a lot of client
support out there. And while the above templates are straightforward,
once you say that a link target is a URI template the client must
support all aspects of the template syntax.

Cheers,
Mark.

[1] - http://docs.redhat.com/docs/en-US/Red_Hat_Enterprise_Virtualization/3.0/html/REST_API_Guide/index.html