openstack/api-sig
Code Issues Proposed changes
api-sig/guidelines/naming.rst
Chris Yeoh e00144c3a0 Moves from markdown to rst 
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
2014-10-22 16:24:41 +10:30

1.3 KiB
Raw Blame History

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.