#!wiki caution
'''These are sample goals an guidelines, they are not official and have not been approved by the PPB'''

Sample API Goals

Stable: Each successive implementation of the APIs should always be backwards-compatible; i.e., a client for the previous release should work with the successive release. Old features / APIs can be phased out in a controlled way.
Broadly Usable: OpenStack APIs should be able to be easily used by a variety of potential clients, not just those using a particular platform, programming language, or data store.
Simple: We prefer simple solutions over layers of complexity. Our users should be able to leverage their existing knowledge, implementations, and tools as much as possible when working with OpenStack APIs. Wherever possible, off-the-shelf technologies and techniques should be used, so as to reduce the amount that potential users need to learn.
Consistent: Our users should also be able to leverage experience with one OpenStack API to quickly get up to speed with another one.
Performant: Our APIs should be as fast as possible.
Browsable: It should be possible to easily build Web browser-based clients for OpenStack APIs, without using extensions or plug-ins.

Sample API Guidelines

An OpenStack API indicates its version in the first path segment, by a "v" followed by an integer; e.g., "http://openstack.example.org/v2/foo". All changes between releases below this point must be backwards-compatible. [stable]
Backwards-incompatible changes (e.g., no longer supporting a resource, changing representation formats) are introduced by incrementing the version identifier. Bumping the version should be done very rarely. When the version is bumped, the most recent version must be supported for at least [n] releases afterwards, preferably longer, and the sunset of the API version needs to be widely announced. [stable]
OpenStack APIs must be based upon the HTTP protocol, and make both JSON and XML representations available [usable, browsable, simple].
Use HTTP GET for retrieval [usable, performant, browsable, simple].
Use hyperlinks with typed relations; don't assume clients will build URIs from IDs. [browsable, simple]
Re-use well-known media types where possible, to avoid format proliferation [simple]
Support HTTP Cache Validation via conditional GET headers. [performant]