Open Stack

The documentation team noticed that we have links in the version
responses of several APIs that contain URLs that do not exist at all.

For example, cinder includes a link to
"http://jorgew.github.com/block-storage-api/content/os-block-storage-1.0.pdf"
- and jorgew.github.com does not exist as host at all.

The links we're concerned about are the links to WADL and PDF files.

Even if we update the links to point to valid URLs, it takes away any
flexibility for the documentation team to move files around on the
server.

Diane Fleming and myself therefore propose to remove all the WADL
links completely and have the PDF links just point to
http://docs.openstack.org. So, moving forward with Juno (unless this
gets backported), the content would be valid.

But what about existing installations that already include links? Some
of the existing links work - or worked a few months ago before some
files got moved around. We could try to fix docs.openstack.org so that
the WADL and PDF links to docs.openstack.org (so, not the cinder example
above) work somehow:
1) Add redirects to current versions of WADL and PDF
2) Add redirects to just http://docs.openstack.org/index.html

Since this affects several projects and is somehow user visible, we
brought it up for discussion here. Note that some of these links seems
to be broken for a very long time. The proposed changes do not break
programs using the API - just users that look at the result of it in
existing installations.

So, my proposal would be:
* Remove WADL links
* Have PDF links to go http://docs.openstack.org
* For those current links to the site http://docs.openstack.org: Take
  care that they point either to a current file or get redirected to
  http://docs.openstack.org/index.html

What do you think?

Andreas

For more details see these bugs:
cinder v2: https://bugs.launchpad.net/cinder/+bug/1313116
cinder v1: https://bugs.launchpad.net/cinder/+bug/1313118
nova v2 and v3: https://bugs.launchpad.net/nova/+bug/1313119
identity v2.0 and v3: https://bugs.launchpad.net/keystone/+bug/1313127

A patch for Cinder is at https://review.openstack.org/90554

-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126