API Guidelines
  • adidas API Guidelines
  • General Guidelines
    • Introduction
    • API First
    • Contract
    • Immutability
    • Robustness
    • Common Data Types
    • Version Control System
    • Minimal API Surface
    • Rules for Extending
    • JSON
    • Security
    • Tooling
  • REST API Guidelines
    • Introduction
    • Core REST Principles
      • OpenAPI Specification
      • API Design Platform
      • Design Maturity
      • Testing
    • Protocol
      • HTTP
      • TLS
      • Separate Concerns
      • Request Methods
      • Status Codes
    • Message
      • Message Formats
      • Content Negotiation
      • HAL
      • Problem Detail
      • Foreign Key Relations
    • Application
      • Corporate Data Model
      • Common Data Types
    • Execution
      • Pagination
      • Long Running Tasks
        • Polling
        • Callback
        • Files Upload
      • Batch Operations
      • Search Requests
      • Query Requests with Large Inputs
      • Choosing Fields and Embedded Resources
      • Localization
      • Rate Limiting
      • Caching
      • Testing Enviroments
    • Evolution
      • Naming Conventions
      • Reserved Identifiers
      • URI Structure
      • Changes and Versioning
      • Phasing out Old Versions
    • Guides
      • API Testing CI Environment
      • Complete API Development
    • API Clients
      • Loose Coupling
    • Further References
  • Asynchronous API Guidelines
    • Introduction
    • Core Asynchronous Principles
      • Event Driven Architectures
      • Messages
        • Commands
        • Queries
        • Events
          • Events as Notifications
          • Events to Replicate Data
      • Protocols
      • Coupling
      • Bounded Context
      • Stream Processing
      • Naming Conventions
      • Tooling
        • Editors
        • Command Line Interface (CLI)
        • Generators
    • Kafka Asynchronous Guidelines
      • Introduction
        • Why AsyncAPI?
      • AsyncAPI Version
      • Internal vs Public Specifications
      • Key/Value Format
      • Message Headers
      • Specification Granularity
      • Self-Contained Specifications
        • Meaningful Descriptions
      • Schema Data Evolution
        • Backward Compatibility
        • Forward Compatibility
        • Full Compatibility
      • Automatic Schema Registration
      • Contact Information
      • AsyncAPI ID
      • Servers
      • Channels
      • Schemas
      • Security Schemes
      • External Docs
Powered by GitBook
On this page
  • General Naming Rules
  • URI
  • Query Parameters and Path Fragments
  • URI Template Variables
  • Representation Format Fields
  • Relation Type Identifier
  • HTTP Headers
  • API Description
  • API Name
  • Resource Name
  • Action Name
  1. REST API Guidelines
  2. Evolution

Naming Conventions

General Naming Rules

  • Use American English

  • Don't use acronyms

  • Use camelCase unless stated otherwise

  • Reconcile terms with adidas CDM

Every identifier MUST be in American English and written in lowercase. An identifier SHOULD NOT contain acronyms. CamelCase (camelCase) MUST be used to delimit combined words.

URI

Every URI MUST follow the General Rules except for the camelCase rule. Instead, a hyphen (-) SHOULD be used to delimit combined words (kebab-case). Besides, a URI MUST NOT end with a trailing slash (/).

Plural nouns SHOULD be used in the URI where appropriate to identify collections of data resources (e.g. /orders, /products).

An individual resource in a collection of resources MAY exist directly beneath the collection URI. (e.g. /orders/{order_id}).

Example

A well-formed URI:

/system-orders/1234/author

Query Parameters and Path Fragments

URI Template Variables

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

Example

A well-formed URI Template Variable:

/system-orders/{orderId}/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"
    }
  },
  "orderNumber": 1234,
  "itemCount": 42,
  "status": "pending"
}

Relation Type Identifier

Example

A well-formed resource representation with custom relation fulfillment-provider:

{
  "_links": {
    "fulfillment-provider": {
      "href": "/users/natalie"
    }
  }
}

HTTP Headers

Example

Order-Metadata-Header: 42

API Description

Naming conventions within API Description document.

API Name

Every API Description API name MUST start with API domain enclosed in square brackets (e.g. [API Domain] My API). Words MUST be separated by space.

Example

swagger: '2.0'
info:
  version: '1.0.0'
  title: '[Demo] Orders API'

Resource Name

Every resource MUST have a name (defined by x-summary field). Resource name MUST be in Title Case. Words MUST be separated by a space.

Example

/orders:
  x-summary: List of Orders

Action Name

Every action (operation) MUST have a name (defined by summary field). Action name MUST be in Title Case. Words MUST be separated by a space.

Example

get:
  summary: Retrieve List of Orders
PreviousEvolutionNextReserved Identifiers

Last updated 4 years ago

Every URI query parameter or fragment MUST follow the General Rules. Also, they MUST NOT clash with the .

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

Every custom MUST be in lowercase with words separated by the hyphen (-).

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

RFC6570
relation identifier
RFC6648
reserved query parameter names