Jump to: navigation, search

Documentation/APISite

What's the API site all about?

The API site is at http://api.openstack.org, going live by 2/13/12. It provides reference information for the OpenStack APIs, starting with Compute and Image, with Identity and Object Storage to follow. There are JSON and XML samples for many of the methods and a search box allows you to search the entire page whether the content is revealed or not. Click the details buttons to expand or contract the content below each PUT/POST/GET/DELETE method.

The API site aims to document the API installation at http://trystack.org. Different OpenStack deployments may choose different API extensions, for example, those are not reflected on this site quite yet.

Who works on the API site?

The API site grew out of the openstack-manuals blueprint, https://blueprints.launchpad.net/openstack-manuals/+spec/api.openstack.org, with the doc core team shouldering much of the work. We are inspired by the Twitter REST API Reference and the The App Garden on Flickr. The API site works hard to separate content from format. The format was built from this mockup, http://heckj.github.com/api-site-mock/. So there are roles for content work and framework work on the API site, all are welcome.

How can I work on the API site?

The framework that builds the site is part of a Maven plugin. The content is stored in the openstack-manuals project in the doc/src/docbkx/openstack-api-site folder. To work on the framework, please contact AnneGentle. To work on the content, please submit patches to the WADLs stored in openstack-manuals (for now) using the Development workflow.

I see a need for some content or format corrections, how can I report the problem?

Please report a bug at http://bugs.launchpad.net/openstack-manuals and tag it with api-site. If you see a problem with the framework, report it in the same way.

What's the source file for the API site?

The content is created from WADL files stored in openstack-manuals right now, but the goal is to move those to the representative API documents in API repositories - openstack/compute-api or openstack/image-api for example.

How often is the API site updated?

There is a Jenkins job that watches for changes to the WADLs in the openstack-manuals repo. It re-builds the site when those changes are approved by the docs core team, but we will move the WADLs to the corresponding API repos so that those core devs can approve changes to the content.