Open Stack

Hi all,
I wanted to point attention to the latest release of 1.15.0 which went out
too close to my newsletter time to make it into What's Up Doc? :)

Andreas has already gotten our repos updated to use this, since it fixed
bug 1289568

In reviewing I noticed that API output changed slightly so I wanted to
bring it to the list to make people aware.

In books that point to WADLs that output to HTML and PDF, such as the
Identity API v2.0 Reference, the URI output displays a leading backslash.

http://docs.openstack.org/api/openstack-identity-service/2.0/content/POST_admin-authenticate_v2.0_tokens_Token_Operations.html

URI: /v2.0/tokens

We can turn this behavior off if needed. There's a parameter that lets you
specify how many items to trim off the front of the uri in wadls:

trimWadlUriCount

So if you set that to 1, it will trim trim first element off the uri, so:

v1/foo/bar

becomes

foo/bar

For the API Reference pages at http://api.openstack.org/api-ref.html the
leading slash is not output.

Here's some evidence that there's no standard, but I do see a pattern for
adding the leading slash. However, it's often with the version number.
Twitter is the only developer reference without leading-slash output. Look
at these:
http://developer.marvel.com/docs: GET /v1/public/characters/{characterId}
https://dev.twitter.com/docs/api/1.1: GET statuses/mentions_timeline
https://developer.linkedin.com/documents/profile-api: GET
http://api.linkedin.com/v1/people/url=<public-profile-url>
http://developer.twilio.com/  /2010-04-01/Accounts/{AccountSid}/Calls
http://developer.github.com/v3/activity/notifications/: GET /notifications

So it really depends on the shape of the service catalog. At this point in
time, OpenStack service catalogs return the version number, but that may
not always be the case.

So my preference would be to add a leading slash but also ensure the
version number of the API is the first part.  I wanted to see if the list
has a preference.

Thanks for reading this far! Sorry no tl;dr!

Anne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140324/0c0eb119/attachment-0001.html>