api-guidelines/evolution/naming-conventions.md

Naming Conventions

General Naming Rules

• Use lowercase ("snake_case")
• Don't use acronyms
• Use underscore to delimit words

Every identifier MUST be in lowercase except for abbreviations. An identifier SHOULD NOT contain acronyms. Underscore (_) MUST be used to delimit combined words.

URI

Every URI MUST follow the General Rules. In addition, an URI MUST NOT end with a trailing slash (/).

Example

A well-formed URI:

/system_orders/1234/author

Query Parameters and Path Fragments

Every URI query parameter or fragment MUST follow the General Rules. In addition, they MUST NOT clash with the reserved query parameter names.

URI Template Variables

In addition to General Naming Rules, URI Template Variable names MUST follow the RFC6570. That is, the variable names can consist only from ALPHA / DIGIT / "_" / pct-encoded.

NOTE: Per RFC6570 Hyphen (-) is NOT legal URI Template variable name character.

Example

A well-formed URI Template Variable:

/system_orders/{order_id}/author

Representation Format Fields

Every representation format field MUST conform to the General Naming Rules.

Example

A well-formed resource representation:

{
  "_links": {
    "self": {
      "href": "/orders/1234"
    },
    "author": {
      "href": "/users/john"
    }
  },
  "order_number": 1234,
  "item_count": 42,
  "status": "pending"
}

Relation Type Identifier

Every custom relation identifier MUST conform to the General Naming Rules.

HTTP Headers

Every HTTP Header should use Hyphenated-Pascal-Case. A custom HTTP Header SHOULD NOT start with X- (RFC6648).

Example