openstack/nova
Code Issues Proposed changes

Add developer policy about contractual APIs

Browse Source 
Document what APIs nova considers to be public contracts, anything not
in this list should be considered a private API.

Clarify the 'API' section to make sure its clear we are talking about
the REST API.

Change-Id: If71adc7a9d5dc1bde79f75d10e67500f6f92b81f
This commit is contained in:
Joe Gordon
2014-09-30 15:30:28 -07:00
parent f5b37bac2e
commit b70ba400ed
1 changed files with 15 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
doc/source/devref/policies.rst
View File

@@ -22,18 +22,29 @@ wiring in out of tree code, upstream doesn't actively make any guarantees
about these extensibility points; we don't support them, make any guarantees
about compatibility, stability, etc.
APIs
=====
Public Contractual APIs
========================
Although nova has many internal APIs, they are not all public contractual
APIs. Below is a list of our public contractual APIs:
* All REST API
Anything not in this list is considered private, not to be used outside of
nova, and should not be considered stable.
REST APIs
==========
Follow the guidelines set in: https://wiki.openstack.org/wiki/APIChangeGuidelines
The canonical source for API behavior is the code *not* documentation.
The canonical source for REST API behavior is the code *not* documentation.
Documentation is manually generated after the code by folks looking at the
code and writing up what they think it does, and it is very easy to get
this wrong.
This policy is in place to prevent us from making backwards incompatible
changes to APIs.
changes to REST APIs.
Patches and Reviews
===================