Open Stack

As part of the api-audit - 
https://blueprints.launchpad.net/nova/+spec/nova-v2-api-audit I was 
brushing up on our docs, and starting to verify that we do what our docs 
say we do.

http://docs.openstack.org/api/openstack-compute/2/content/Versions-d1e1193.html 
says that when you do a GET on /v2/ you get:

  "The detailed version response contains pointers to both a 
human-readable and a machine-processable description of the API service. 
The machine-processable description is written in the Web Application 
Description Language (WADL)."

If you do that for nova (grizzly) today you get the following (more 
details in https://bugs.launchpad.net/nova/+bug/1076109/)

... "links": [
    {"href": "http://9.114.219.71:8774/v2/", "rel": "self"},
    {"href": 
"http://docs.openstack.org/api/openstack-compute/1.1/os-compute-devguide-1.1.pdf", 
"type": "application/pdf", "rel": "describedby"},
    {"href": 
"http://docs.openstack.org/api/openstack-compute/1.1/wadl/os-compute-1.1.wadl", 
"type": "application/vnd.sun.wadl+xml", "rel": "describedby"}
]

The describedby urls are both for version 1.1, as well as not actually 
working.

Docs don't match code. We need to fix one or the other. I think this one 
should fix in code, the docs make sense.

This is a bug that we can fix, but the real question is where we should 
cannonically put the wadl file.

The PDF has an updated url we can use.

The WADL isn't directly accessible on the docs.openstack.org site, so 
the only live link is github, which is bad. I think we need a stable 
place for the wadl file here off the docs.openstack.org site.

The one question that was raised in talking with the doc team is were 
these urls intended to be actual urls or just namespaces. The docs seem 
pretty clear to me these are actual urls, so we need them to actually 
exist. But other opinions welcome. :)

	-Sean

-- 
Sean Dague
IBM Linux Technology Center
email: sdague at linux.vnet.ibm.com
alt-email: sldague at us.ibm.com