Skip to main content

API Design and Naming Conventions

Endpoint URL Structure​

The endpoint structure MUST be resource-oriented to keep the API clear and understandable. Resource-oriented URLs are based on the main resources of the API and reflect the structure and relationship of the data. Using nouns instead of verbs helps make the API more intuitive and logical.

Example:
Instead of using verbs in the endpoints, the focus should be on the resource being addressed.

  • Bad: POST /createUser or GET /fetchOrders
  • Good: POST /users to create a user and GET /orders to retrieve orders.

For hierarchical structures, sub-resources SHOULD be used to represent clear relationships. This helps clarify the relationship between parent and child resources and makes navigating the API easier.

Example:
If an API is designed for a bike leasing system, the structure might look like this:

  • GET /users/{userId}/orders — returns all orders for a specific user. Here, {userId} is a placeholder for the user ID, and the request returns all orders associated with that user.
  • GET /contracts/{contractId}/details — returns all details of a specific leasing contract. In this case, {contractId} represents the specific contract ID for which details are being requested.
  • GET /bikes/{bikeId}/accessoires — returns all accessories for a specific bike. Here, {bikeId} represents the specific bike ID for which accessories are being requested.

The plural form SHOULD be used for resource names to ensure a consistent and predictable URL structure.

Example:
GET /products for a list of products and GET /products/{productId} for a specific product.

All endpoint URLs MUST be written in kebab-case. This applies to resource names and all path parameters. This ensures a consistent and easily readable API structure.

  • Bad: /bikeLeasings/{leasingId}/details
  • Good: /bike-leasings/{leasing-id}/details

Resources and Collections​

Resources MUST be treated as entities that can be addressed by unique identifiers (IDs). Each resource should have a unique URL and be manipulable through that URL.

Example:
A specific bike could be addressed via the URL:
GET /bikes/{bikeId}

Resources in collections and individual items MUST be distinguished, where collections represent URLs for lists of resources, and individual items represent URLs for specific resources.

Example:

  • GET /bikes – Lists all bikes.
  • GET /bikes/{bikeId} – Returns details of a specific bike.

Consistent Naming (Nomenclature)​

Naming Conventions:
Consistent naming conventions MUST be applied to ensure a clear and uniform API structure.

Path parameters, endpoint URLs, and headers MUST use kebab-case to improve readability and maintain a consistent structure.

  • Bad: /bikeLeasings/{leasingId}/details
  • Good: /bike-leasings/{leasing-id}/details

Query parameters and JSON data fields MUST use camelCase to ensure uniform data formatting and compatibility.

  • Bad: start_date, user_id, order_amount
  • Good: startDate, userId, orderAmount

Descriptive Naming:
Names of resources and parameters SHOULD be descriptive and self-explanatory to enhance the clarity of the API. Avoid using shortened or cryptic names that might cause confusion.

Example:
Instead of a vague name like usr, use user to clearly indicate the purpose of the parameter or resource.

Consistency Across the API:
Consistent naming MUST be maintained across all publicly available endpoints and resources. All APIs within the system should use the same naming conventions and styles to ensure a cohesive user experience.

Example:
If firstName is used for the user resource, other resources like customer or employee MUST also adopt this convention.

Avoiding Abbreviations:
Abbreviations SHOULD be avoided unless they are widely accepted and well understood. Clarity should always take precedence to prevent misunderstandings and make the API documentation more accessible.

Example:
Use productDetails instead of prdctDtl for data fields or parameter identifiers.

Handling Multi-word Names:
For names consisting of multiple words, camelCase MUST be used, with the first word starting in lowercase and subsequent words starting with an uppercase letter.

Example:
orderDate, userEmailAddress, productList

API Versioning​

Unique Identification by Version Number:
Each API version MUST be clearly identified by including the version number in the URL. This allows for clear differentiation between API versions and facilitates managing changes without disrupting existing integrations.

Example:

  • GET /v1/products — for the first version of the API providing a specific functionality
  • GET /v2/products — for the second version of the API, offering new features or changes while continuing to support the first version

Consistent Versioning:
A consistent method for versioning SHOULD be used. The version number should be clearly indicated in the URL structure and ideally consist only of major versions. Versions are denoted as v1, v2, and should only be incremented when significant changes are made to the API that might not be backward compatible.

Maintenance and Support of Older Versions:
Older versions of the API MUST continue to function as long as needed, and all changes in new versions must be documented. Support for deprecated versions SHOULD be phased out within a clearly defined timeframe to give users sufficient time to migrate.

Example:
An API version v1.0 might be supported for one year before entering maintenance mode, while version v2.0 provides new features.

Thorough Documentation of Versions:
API versions MUST be thoroughly documented, including the specific differences and changes between versions. This helps developers understand the changes and adjust accordingly.

Example:
The documentation for version v2.0 should describe all new endpoints, modified parameters, and backward compatibility with earlier versions.

Minimizing Versioning:
API design MUST aim to minimize versioning and introduce new versions only when absolutely necessary. The primary goal should be to avoid breaking changes by adapting existing APIs through extensions rather than through radical changes. Changes to existing fields or endpoints should be designed to be backward compatible to avoid disrupting existing integrations.

Example:
When adding a new data field to a resource, this field should be made optional so that existing clients can continue to work with the existing fields without needing to make changes.

Extensions Instead of Changes:
Changes SHOULD be made through extensions to the existing API functionality. This includes adding new fields or optional parameters rather than removing or altering existing fields. This strategy helps avoid breaking changes and reduces the need for a new version. Care MUST be taken to ensure that consuming clients can handle the additional data fields.

Example:
If a new field deliveryDate is added to an existing endpoint GET /orders, it should be integrated as an optional field so that existing clients can continue to operate without adjustments.

Consistent Versioning of All Related APIs:
If versioning becomes necessary, all relevant APIs that are interconnected MUST also be versioned. This means that changes to one API, which are linked to others, must result in a simultaneous version increment for all affected APIs to ensure consistency and integrity.

Example:
If a fundamental change to GET /orders requires a new version v2, then GET /items and all other APIs linked to orders MUST also be updated to v2 to ensure uniform versioning and compatibility.