e00144c3a0
Changes format of files from markdown to reStructuredText and adds the tox targets to verify the format and build the html. Also adds bits and pieces needed to finish bootstrapping the repository. Change-Id: If559c21f19d7044a0d89b29e5743bf09c9da2ac1
38 lines
1.3 KiB
ReStructuredText
38 lines
1.3 KiB
ReStructuredText
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.
|