API Bites — API Path Conventions

Predictable API Path Conventions

Published in

API Central

6 min readSep 1, 2022

The structure of the URLs by which Business Resource APIs are addressed should be consistent, predictable, and meaningful to clients. Enterprise guidance on URI and path composition can ensure clarity of API context and intent, and therefore usability.

URI and FQDN

URI Constraints

URI structure and semantics must follow RFC 3986 constraints at a minimum. The following constraints are also commonly applied by API design guidance:

the URI should not contain capital letters. Alphabetic characters should be lower case only
for improved readability, only hyphens ‘-’ should be used to separate words or path parameters. Avoid spaces or underscores.
query parameter names must align with enterprise field naming conventions (e.g. camelCase or snake_case)

URI Components

The following describes a high-level breakdown of URL component parts:

Authority / FQDN

The fully-qualified domain name (FQDN), or authority, may incorporate global API context, including the use-case, business domain and environment. A consistent enterprise scheme should be followed, such as:

The use-case context (e.g. ‘api’) should constitute the first name part.
An environment identifier (e.g. ‘test’) MAY follow (typically non-prod environments only).
The core business domain (e.g. ‘store’) MAY follow.

For example:

https://api.myorg.comhttps://api.test.myorg.comhttps://api.dev.store.myorg.com

In a hybrid cloud environment (in the absence of a sophisticated DNS/point-of-entry network architecture) the FQDN might also include a platform/DNS-zone name part, such as '.gw1' or '.cl1' or '.azr|aws|gcp'

https://api.aws.myorg.com

Domain Context | Namespace

The resource context, or name-space, is derived from a combination of the Fully Qualified Domain Name (FQDN) and the resource path contained in the resource URL.

The domain root is the top-level domain name controlled by the organisation — e.g. ‘myorg.com’. Lower level domain identifiers may optionally be encapsulated in the FQDN to the left of the root-domain, and/or to the right of the FQDN in the resource path. The following URLs express a fundamentally equivalent domain hierarchy:

api.store.myorg.com/v1/productsapi.myorg.com/store/v1/products

How an API resource context is expressed will be driven by organisational, DevOps, platform, hosting and domain integration considerations.

Building the API Path

The following path convention provides consistent addressability of business information resources. It breaks the URI path structure down into more granular components, contingent on the particular use-case:

Path Context

Resource service context (or name-spacing) derived from a business domain/sub-domain hierarchy may be provided at the root of the path.

Where a Fully Qualified Domain Name (FQDN) uniquely identifies the business/capability domain, a root name-space in the path is optional, however if an FQDN does not uniquely identify the business/capability domain, a root or sub-domain namespace must be defined in the API path to provide context and control resource name clashes. As per the pattern api.[root-domain]/[service-domain]/… e.g.

https://api.myorg.com/membership/

API Version

When API URLs are versioned, they must only include the MAJOR version as part of the URI, in the format ‘v{MAJOR}’, e.g.

https://api.myorg.com/membership/v1/

Minor and patch versions (assuming SemVer versioning) must NOT be included in the URI as such changes are by definition backwards-compatible.

The version number refers to the following versioned resource API.

API versioning strategies are discussed in more detail here.

Resource Name

Modellers should follow these principles when creating a REST API:

Resource names must be plural nouns when referring to a resource collection (there are potentially a number of instances) e.g. ‘/users’. A singleton, such as ‘/users/1234/cart’ must be singular.
Resource names should be lower-case and use only alphabetic characters, with hyphens employed to separate words.

https://api.myorg.com/membership/v1/applications

Note: URIs are the only place where hyphens are used as a word separator. In all other situations, the word separation scheme should align with enterprise field naming conventions (e.g. camelCase or snake_case).

Resource Identifiers

Every business information resource that is available within your business domain (e.g. every applicant and every application) must be identifiable uniquely within the domain. This is a key element of the RESTful style; the ability to individually address any resource within your domain and store these identifiers for later use.

https://api.myorg.com/membership/v1/applications/12345

Identifier Format

A resource identifier can be a string or numeric value, and must be URL safe. A protected or confidential resource identifier must be un-guessable and non-sequential, providing maximum abstraction from Personally Identifiable Information, primary keys, and time or order of creation. This requirement may be met with a randomly generated unique identifier, e.g.

/v1/applicants/538d9bb1

The resource identifier must be immutable.

Sub-resources and URL Resource Levels

Sub-resources are typically existentially dependent (should not exist without) are subordinate to the parent.

If sub-resource represents a value object, it will be addressed as an object, collection or singleton belonging to a resource instance, e.g.

v1/products/12B34C/specification

Some sub-resources may be independently addressable, and will have a unique Id e.g. A path to the collection should be provided in the context of the parent instance.

v1/members/12B34C/dependents andv1/members/12B34C/dependents/98Y76X

In the latter case, consider if there are valid use-cases for interaction with the resource without knowledge of or interest in the parent instance. If this is the case, a flatter path structure might also be provided e.g.

v1/members/dependents/98Y76X

Resource models SHOULD not require more than 2 levels of resource in your URL — multiple resource levels can make APIs complex to understand and can reduce the intelligibility and usability of your API.

If the model calls for something more than /resource/{resourceId}/resource/ then reconsider the granularity of the model.

More detail here : Modeling Coherent and Composable Business Resource APIs

Common Functional Use-Case Design Patterns

Design patterns support specific functional use case patterns in relation to a business resource.

Canonical business resource pattern

The business resource represent the nouns of a system, such as ‘applications’ and ‘applicants’.

Format:
/{version}/{resource}/{resourceId}Example:
GET /v1/subscriptions/12B34C

Parameter-driven filtering

A decoupled convention-over-configuration approach to filtering & field selection based on the business-information-resource model

Format:
/{version}/{resource}/{resourceId}?fields={name}/{version}/{resource}?{fieldName}={value}&fields={name1,name2}Example:
GET /v1/claims?customerId=12B34C&fields=claimId,name

Command affordance pattern

A pattern to afford explicit state transitions or provide abstract functionality in the context of a business resource, or capability domain. The action is expressed as a verb that acts in the context of a resource instance or resource collection.

Format:
/{version}/{resource}/{resourceId}/{affordance-name}/{version}/{resource}/{affordance-name}Example:
https://api.myorg.com/membership/v1/applications/12345/cancel

Versions pattern

Where versioned resource instances are maintained, such as document versions
Typically the version-id is an incrementing integer
GET request on the base resource always returns the latest version

Format:
/{api-version}/{resource}/{Id}/versions/{versionId}Examples:
GET /v1/activity-reports/12345/versions/3GET /v1/activity-reports/12345           --> Latest

Job to be done (JTBD) pattern

Some specific process or regulatory obligation related to a business resource.

Format:
/{version}/{resource}/{job name}/{jobId}Example:
POST /v1/consignments/receivals/987654

Wrap-up

We have seen that strong API path conventions can provide clarity context and intent, improving the intelligibility and predictability of enterprise APIs. Familiar and easy-to-navigate conventions assist both API developers and API clients, and support and encourage self-service integration and API re-use.