5289de666d
This guideline document describes the implementation of tagging in REST APIs. Change-Id: I53e11690ed04d46d4dcd089267b0fd9bee729692
40 lines
1.3 KiB
ReStructuredText
40 lines
1.3 KiB
ReStructuredText
.. _naming:
|
|
|
|
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.
|