Resource Naming and URI Design

Use lowercase hyphen-separated words for static path segments

Static URI path segments must use lowercase words separated by hyphens.

Examples:

/node-groups
/locked-cells

This rule applies only to static path segments and does not apply to path parameter names.

Path parameters can be used in any URI path segment

Path parameters may appear at the end of a URI or within any other path segment.

Examples:

/cells/{id}

/cells/{id}/adjacent-cells

/nodes/{id}

/nodes/{id}/connected-nodes

/node-groups/{id}

/node-groups/{id}/nodes

Prefer id as the primary identity attribute

Resources should use a unique id attribute as the primary identity attribute.

The id value should be unique at least within the scope of the resource collection where the object is exposed.

Example:

Request:

GET /nodes/123 HTTP/1.1

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "123",
  "userLabel": "KistaEast",
  "ipAddress": "192.168.1.1"
}

In this example:

• id is the primary identifier.
• userLabel and ipAddress are secondary identifiers.

Natural keys from the business domain may also be used when their uniqueness can be guaranteed.

Matrix parameters may be used for secondary identifiers

Primary identifiers should normally be represented as path parameters:

/nodes/{id}/connected-nodes

Secondary identifiers should be qualified with their attribute names and may be represented using matrix parameters.

Examples:

Primary identifier:

/nodes/{id}/connected-nodes

Matrix parameters:

/nodes/userLabel={userLabel}/connected-nodes

/nodes/ipAddress={ipAddress}/connected-nodes

Multiple matrix parameters:

/nodes/ipAddress={ipAddress}/connected-nodes/cabinetName={cabinetName1},{cabinetName2};operationalState={operationalState}

Matrix parameters provide a way to include named attributes directly within URI path segments.

Use camelCase for matrix path parameters

Matrix path parameters must use camelCase.

Do not use:

• snake_case
• kebab-case

Examples:

Correct:

/nodes/userLabel={userLabel}/connected-nodes

/nodes/ipAddress={ipAddress}/connected-nodes

Incorrect:

/nodes/user_label={user_label}

/nodes/ip-address={ip_address}

This rule does not apply to simple path parameters representing primary identifiers.

Example:

/nodes/{id}

Use camelCase for query parameters

Query parameters must use camelCase.

Do not use:

• snake_case
• kebab-case

Examples:

Correct:

customerNumber

orderId

billingAddress

ipAddress

Incorrect:

customer_number

order-id

billing_address

Prefer hyphenated Pascal Case for HTTP header fields

HTTP header fields should preferably use hyphenated Pascal Case for consistency.

Common abbreviations such as ID may remain uppercase.

Examples:

Accept-Encoding

Apply-To-Redirect-Ref

Disposition-Notification-Options

Original-Message-ID

HTTP header names are case-insensitive according to HTTP standards.

Use plural resource names

Resource names should use plural forms.

Most REST APIs expose collections of resources, even when a resource currently contains only one instance.

Examples:

Correct:

/users

/orders

/products

/devices

Avoid:

/user

/order

/product

/device

A singleton resource can still be modeled as a collection with a cardinality of one.

Avoid /api as the base path

The API base path should normally not contain /api.

Preferred:

/customers

/orders

/devices

Avoid:

/api/customers

/api/orders

/api/devices

The deployment base path should be treated as deployment configuration and defined separately from resource paths.

Avoid trailing slashes

Resource URIs should not end with trailing slashes.

Preferred:

/customers/123

Avoid:

/customers/123/

Resources should behave consistently regardless of trailing slash handling, but clients and servers should use the non-trailing-slash format.

Standard Query Parameters

APIs supporting searching, sorting, filtering, and pagination should use conventional query parameter names.

Search

Use:

q

Example:

/products?q=phone

q represents user-entered search terms.

Sorting

Use:

sort

The value is a comma-separated list of fields.

Example:

/orders?sort=id

Sorting direction can be specified using prefixes:

Ascending:

/orders?sort=+id

Descending:

/orders?sort=-createdAt

Multiple fields:

/orders?sort=-createdAt,status

Partial response fields

Use:

fields

Example:

/users?fields=id,name,email

This allows clients to request only required fields.

Embedding related resources

Use:

embed

Example:

/orders?embed=customer

This allows related resources to be included inline in the response.

Offset pagination

Use:

offset

Example:

/orders?offset=100

offset specifies the position of the first element returned in a collection.

Cursor pagination

Use:

cursor

Example:

/orders?cursor=eyJwYWdlIjoyfQ==

The cursor should be treated as an opaque value.

Clients must not inspect, modify, or construct cursor values.

Page size limitation

Use:

limit

Example:

/orders?limit=50

limit allows clients to suggest the maximum number of resources returned in one response.