Adds topic document for naming conventions
This commit is contained in:
parent
d04cd7c363
commit
6381e49fc1
@ -17,6 +17,7 @@ specific issue:
|
|||||||
|
|
||||||
* [Terms](terms.md)
|
* [Terms](terms.md)
|
||||||
* [HTTP Response Codes, Methods, and Standards](http.md)
|
* [HTTP Response Codes, Methods, and Standards](http.md)
|
||||||
|
* [Naming Conventions](naming.md)
|
||||||
* [API Discoverability](discoverability.md)
|
* [API Discoverability](discoverability.md)
|
||||||
* [Compatibility](compatibility.md)
|
* [Compatibility](compatibility.md)
|
||||||
* [API Extensions](extensions.md)
|
* [API Extensions](extensions.md)
|
||||||
|
35
naming.md
Normal file
35
naming.md
Normal file
@ -0,0 +1,35 @@
|
|||||||
|
Naming Conventions
|
||||||
|
==================
|
||||||
|
|
||||||
|
This topic document serves to provide guidance on how to name resources in
|
||||||
|
OpenStack public REST APIs so that our APIs feel consistent and professional.
|
||||||
|
|
||||||
|
REST API resource names
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
* A resource in a REST API is always represented as the plural of an entity that is exposed by the API.
|
||||||
|
|
||||||
|
* Resource names exposed in a REST API should use all lowercase characters.
|
||||||
|
|
||||||
|
* Resource names *may* include hyphens.
|
||||||
|
|
||||||
|
* Resource names should *not* include underscores or other punctuation (sole exception is the hyphen).
|
||||||
|
|
||||||
|
Fields in an API request or response body
|
||||||
|
-----------------------------------------
|
||||||
|
|
||||||
|
HTTP requests against an API may contain a body which is typically a serialized
|
||||||
|
representation of the resource that the user wished to create or modify.
|
||||||
|
Similarly, HTTP responses contain a body that is usually the serialized
|
||||||
|
representation of a resource that was created, modified, or listed by the
|
||||||
|
server.
|
||||||
|
|
||||||
|
Fields within these serialized request and response bodies should be named
|
||||||
|
according to these guidelines:
|
||||||
|
|
||||||
|
* Field names should use `snake_case` style, *not* `CamelCase` or `MixedCase`
|
||||||
|
style.
|
||||||
|
|
||||||
|
**TODO** Add patch proposing guidelines for how to name boolean fields.
|
||||||
|
|
||||||
|
**TODO** Add patch proposing guidelines for naming state/status fields.
|
Loading…
x
Reference in New Issue
Block a user