api.openstack.org

For implementors and contributors, we need to have a way to present API documentation in a fashion that is quick to digest across multiple openstack projects. The dev.twitter.com page was mentioned as an example, but we should probably focus first on API doc.

Product: api.openstack.org

Problem Statement: Currently, API information is in individual service documentation and isn't tied together neatly for developers and implementors to consume. For example, if an implementor wanted to see what URIs the OpenStack APIs accept and block any others, they would have to find and read the API docs for each individual service.
If the presentation of API documentation causes frustration, then adoption of OpenStack services as a whole would be challenging.
Proposed solution:

    Display APIs in a style similar to dev.twitter.com/docs/api - something that shows the verb, resource, and description for all API calls.

    Detail can be retrieved easily for the call. This detail includes:

    Parameter (including if it's optional or not)

    Parameter description

    Drop down box showing JSON or XML

    If JSON is triggered in the drop down box, then JSON request and response for the call is shown.

    If XML is triggered in the drop down box, then XML request and response for the call is shown

    Provide a search box that will find the queried content and expand the containing section as necessary if query is in a hidden div (jQuery magic can do this)

    Content updates triggered from successful jenkins reviews.

Please see the full specification for open questions and issues.