RESTful API Naming Conventions: Best Practices for Clarity and Consistency

Introduction

When designing a RESTful API, consistency in naming conventions is crucial for ease of use, maintainability, and clarity. Clear and descriptive endpoint names make it easier for developers to understand the purpose of each endpoint and ensure a consistent user experience.

This article explores best practices for naming conventions in RESTful APIs, with examples based on typical use cases.

1. Use Nouns for Resources

The key principle of RESTful API design is to treat endpoints as resources, not actions. Resource names should be nouns representing entities in your application.

Example

Instead of using action verbs like /getVendor or /createVendor, use nouns that represent the resource itself:

//Example
https://smartaccount.com/vendors // Retrieve all vendors
https://smartaccount.com/vendors/{id} // Retrieve a specific vendor

• Plural nouns are used to represent collections (e.g., vendors).
• Singular nouns are used to represent specific entities (e.g., vendors/{id}).

2. Use Consistent Pluralization

Always use plural nouns for collections, even if the endpoint is likely to return a single item at times. This ensures consistency across all endpoints and aligns with RESTful best practices.

Example

• Correct: https://smartaccount.com/vendors – For retrieving a collection of vendors.
• Incorrect: https://smartaccount.com/vendor – Avoid using singular forms for collections.

//The same applies to other entities:
https://smartaccount.com/products // Collection of products
https://smartaccount.com/orders // Collection of orders

3. Hierarchical Structure for Nested Resources

When resources are logically related, use a hierarchical structure to represent these relationships. This improves clarity and makes it clear that one resource is a subset or child of another.

Example

//Instead of using flat or ambiguous endpoint names:
https://smartaccount.com/billHeadersByVendorId/{vendorId} // Ambiguous

//Use a hierarchical structure to clearly indicate the relationship:
https://smartaccount.com/vendors/{vendorId}/bill-headers // Nested

In this case, the nested endpoint clarifies that bill headers are associated with a specific vendor.

4. Use Filtering as Query Parameters

When applying filters, such as date ranges or other parameters, use query parameters rather than path variables. This differentiates core resource identification from optional filtering.

Example

//Instead of:
https://smartaccount.com/totalAmountVendorLedger/{companyId}/{accountIds}/{fromDate}/{toDate}

//Use query parameters for filtering:
https://smartaccount.com/companies/{companyId}/vendor-ledger/total-amount?accountIds={accountIds}&fromDate={fromDate}&toDate={toDate}

This approach makes it clear that the endpoint represents a vendor ledger, while the query parameters are optional filters.

5. Use Clear Action Names for Status Transitions

When an endpoint involves changing the state of a resource, use clear, descriptive names. Use sub-resources like /next or /previous to indicate state transitions.

Example

//Instead of:
https://smartaccount.com/updateNextBillStatus

//Use a more descriptive approach:
https://smartaccount.com/bill-statuses/next // Update to the next status

This structure clarifies that the operation is related to transitioning to the next status of a bill.

6. Use Singular Nouns for Sub-Resources

When dealing with a specific sub-resource of a resource, use singular nouns to represent that specific entity.

Example

• Correct: https://smartaccount.com/vendors/{vendorId}/address – Represents the specific address of a vendor.
• Incorrect: https://smartaccount.com/vendors/{vendorId}/addresses – Misleading, as it suggests multiple addresses.

7. Use Standard HTTP Methods

RESTful APIs rely on standard HTTP methods to define the type of operation on a resource:

• GET: Retrieve a resource or a collection of resources.
• POST: Create a new resource.
• PUT: Update a resource.
• DELETE: Remove a resource.

Example

For managing a vendor’s bank account:

POST: https://smartaccount.com/vendor-bank-accounts // Create a new bank account
PUT: https://smartaccount.com/vendor-bank-accounts/{id} // Update a bank account
DELETE: https://smartaccount.com/vendor-bank-accounts/{id} // Delete a bank account\

8. Avoid Verbs in URLs

In RESTful API design, the HTTP method itself defines the action, so verbs in URLs are generally unnecessary. Use the appropriate HTTP method instead of including verbs in the endpoint name.

Example

• Correct: POST https://smartaccount.com/vendors – To create a vendor.
• Incorrect: POST https://smartaccount.com/createVendor – Redundant verb.

9. Use Meaningful Names for Resource Attributes

Whenever possible, use meaningful names that reflect the purpose of a resource or action. Avoid using cryptic abbreviations or terms that might be unclear to other developers.

Example

//Instead of:
https://smartaccount.com/billStatuses

//Use more descriptive terms like:
https://smartaccount.com/bill-statuses

This minor adjustment makes the endpoint easier to understand, especially for new developers working with the API.

Conclusion

Good naming conventions in RESTful API design enhance readability, maintainability, and scalability. By following the guidelines above, you ensure that your API is intuitive and easy to use. Consistent naming makes the API predictable, reduces confusion, and improves the developer experience.

Whether you’re creating endpoints for vendors, bills, products, or any other resource, applying these best practices will result in a cleaner, more effective API.