While looking for API documentation and specification, as I'm writing a new language binding, I came across api.openstack.org. However, I've simply not been able to find anything approximating a usable set of API docs on this site.
In particular,
1. Open a new tab in the browser, and go to http://api.openstack.org
2. Click on API Specifications
3. Click on OpenStack Identity Service API v2.0 Specification.
4. Scroll down and click on 2.1. Token Operations
5. Drop jaw in incredularity. Where is the spec?
The whole reason I landed on the spec is because the "complete reference," similarly, is inadequate from a software engineering
stand-point. Case in point:
1. As above.
2. Click on API Complete Reference
3. Nice! The token endpoint is right there! Click on Details, and see what it says.
4. Nice! Convenient access to the request format.
5. Uh oh -- where are field descriptions? Where are the special cases? (e.g., nothing indicates that the tenantName field is, in
fact, optional.) But even more importantly, where is the response format? Did I miss something?
Right now, my preferred source of reliable documentation for this is, ironically, Rackspace's own API documentation. However, with the point of my project being to support multiple vendors, it would be really quite awesome if Openstack themselves could have this information in a readily accessible form, so that I don't have to hunt through a plurality of corporate documentation sites as well. This would make it much easier for me to distinguish what is and what is not, say, Rackspace-specific functionality.
I would have expected OpenStack to own its definitive specification on what these APIs mean, what parameters are taken, and what results are given in what circumstances, *and* any side-effects they might have. That's what it means to be a specification. What I'm finding now isn't a specification; more of a sales brochure.
Sam, thanks for reporting. The rest of the specifications should have:
sample request and response in JSON and XML
tables of parameters, whether they are required or optional
Our goal with these specs is to share with all the vendors, HP and Rackspace can consume the information from OpenStack docs since they are licensed for sharing. That happened a lot early on in the project, but has not seen full potential for that "one source of truth" that a standard should be. Our goals with the docs are to live up to being a standard and we strive for that by incrementally improving each project's documentation.