Skip to content

Latest commit

 

History

History
104 lines (79 loc) · 3.16 KB

naming.adoc

File metadata and controls

104 lines (79 loc) · 3.16 KB
Raw

API Naming

{MUST} Use lowercase separate words with hyphens for Path Segments

Example:

/shipment-orders/{shipment-order-id}

This applies to concrete path segments and not the names of path parameters. For example {shipment_order_id} would be ok as a path parameter.

{MUST} Use snake_case (never camelCase) for Query Parameters

Examples:

customer_number, order_id, billing_address

{MUST} Use Hyphenated HTTP Headers

{SHOULD} Prefer Hyphenated-Pascal-Case for HTTP header Fields

This is for consistency in your documentation (most other headers follow this convention). Avoid camelCase (without hyphens). Exceptions are common abbreviations like “ID.”

Examples:

Accept-Encoding
Apply-To-Redirect-Ref
Disposition-Notification-Options
Original-Message-ID

{MAY} Use Standardized Headers

Use this list and mention its support in your OpenAPI definition.

{MUST} Pluralize Resource Names

Usually, a collection of resource instances is provided (at least API should be ready here). The special case of a resource singleton is a collection with cardinality 1.

{MAY} Use /api as first Path Segment

In most cases, all resources provided by a service are part of the public API, and therefore should be made available under the root “/” base path. If the service should also support non-public, internal APIs — for specific operational support functions, for example — add “/api” as base path to clearly separate public and non-public API resources.

{MUST} Avoid Trailing Slashes

The trailing slash must not have specific semantics. Resource paths must deliver the same results whether they have the trailing slash or not.

{MAY} Use Conventional Query Strings

If you provide query support for sorting, pagination, filtering functions or other actions, use the following standardized naming conventions:

  • q — default query parameter (e.g. used by browser tab completion); should have an entity specific alias, like sku

  • limit — to restrict the number of entries. See Pagination section below. Hint: You can use size as an alternate query string.

  • cursor — key-based page start. See [pagination] section below.

  • offset — numeric offset page start. See [pagination] section below. Hint: In combination with limit, you can use page as an alternative to offset.

  • sort — comma-separated list of fields to sort. To indicate sorting direction, fields my prefixed with + (ascending) or - (descending, default), e.g. /sales-orders?sort=+id

  • fields — to retrieve a subset of fields. See Support Filtering of Resource Fields below.

  • embed — to expand embedded entities (ie.: inside of an article entity, expand silhouette code into the silhouette object). Implementing “expand” correctly is difficult, so do it with care.