Open Stack

<http://docs.openstack.org/cactus/openstack-compute/developer/openstack-compute-api-1.1/os-compute-devguide-cactus.pdf>, April 25 2011

I've made focussed comments in the online comment facility, as requested. Many of the issues I saw had to do with misuse of HTTP status codes or re-specification of HTTP functions; please pay particular attention to those.

I also have some general comments which don't really belong to any one section, so I'll give them here.

Overall, I like the focus on JSON as a default over XML. If anything, I'd encourage you to deprecate the XML serialisation and move away from it in 2.0. IME, 90% of the interoperability problems in HTTP Web Services are XML-related, due to incompatibilities with object bindings with different languages, limitations in and complexity of XML Schema (which inevitably some people will try to use, even if you don't specify it), and the complexity of the XML Infoset itself. 

WIth regards to UUIDs -- I'm not sure what the use cases being discussed are (sorry for coming in late), but in my experience UUIDs are good fits for cases where you truly need distributed extensibility without coordination. In other uses, they can be a real burden for developers, if for no other reason than their extremely unwieldy syntax. What are the use cases here?

A few nits about the document itself, generally --

 - It'd be really nice to have a revision identifier.

 - In many of the examples, the HTTP response headers and/or request headers are omitted. IME this often causes confusion and bugs, because developers don't understand the context of the request or response.

 - Finally, could you possibly make the PDF version NOT have grey backgrounds for all of the examples? It wastes a lot of ink...

Cheers,

--
Mark Nottingham   http://www.mnot.net/