Open Stack

On Thu, Nov 8, 2012 at 6:24 AM, Sean Dague <sdague at linux.vnet.ibm.com> wrote:
> 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. :)

Just to clarify, there isn't really a "docs team" for APIs - just
hasn't generated enough interested people to be a "team" :) - but my
question was about whether these are meant to be real URLs. We can
make them real URL, but it's probably better to fix the code to avoid
confusion, since it doesn't sound like it'll break anyone. In this
case, these are not namespaces, they are direct links to specific
files.

I see in the comments in https://bugs.launchpad.net/nova/+bug/1076109
that you've found direct links, the next question is, is pointing to a
github link "static" enough? Generally no. Part of the patch should
also be to create a Jenkins job to copy the correct WADL to the docs
site automatically. I'll also comment on the bug that the more updated
WADL is https://github.com/openstack/api-site/blob/master/api-ref/src/wadls/compute-api/src/os-compute-2.wadl
which is not related to the spec WADL. As far as I can tell, the
spec's WADL has not been updated, for example, MetadatList on Network
IDs are commented out on the one for the API site and in the spec WADL
it remains.

So another question is, which WADL is correct to return to users? The
one that is the spec or the one that is most updated?

Thanks for digging into this Sean - it's snarly.
Anne

>         -Sean
>
> --
> Sean Dague
> IBM Linux Technology Center
> email: sdague at linux.vnet.ibm.com
> alt-email: sldague at us.ibm.com
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev