REST API URL Naming Conventions and Best Practices

Today in this article will learn about REST API URL Naming Conventions and Best Practices.

Stateless protocol and specifications with standard REST operations like GET, HEAD, POST, PUT, PATCH, DELETE, CONNECT, OPTIONS, and TRACE, help to attempt to create very high-performance, reliable Services/API/Micro-services.

Today in this article, we will cover the following aspects,

Resource is Prime

All REST principle and architecture style has a Resource at their heart. These are architectural style that defines a set of specifications to be used for creating API/Services/Micro-services.

Each REST URI should follow a set of syntax rules and should maintain the identification of resources that enables interaction with representations of the resource over a network.

We will see below a few examples of GET, HEAD, POST, PUT, PATCH, and DELETE.

A few best practices are as below,

URL Structure – API URL Naming Conventions

URL should be human-readable. Well-defined URL brings uniformity, easy discovery, and easy adoption across the enterprise.

Use descriptive and meaningful names.

Choose clear and concise names that accurately represent the purpose and functionality of the resource or action.

Avoid cryptic abbreviations or acronyms that may be confusing to API consumers.

An example of a well-structured URL is:

https://www.thecodebuzz.com/v1.0/orders/{order-id}

An example URL that is not friendly is:

https://www.thecodebuzz.com/GetOrder/OMS/BDS/{order-id}

We shall see more details on URL naming below.

Use Nouns in URL and Avoid CRUD verbs in URL

URL should contain nouns and should restrain using verbs like GetData, UpdateData, etc.

Bad Example:

https://thecodebuzz.api/v1.0/GetOrders/{order-id}  

https://thecodebuzz.api/v1.0/DeleteOrders/{order-id} 

Good Example

https://thecodebuzz.api/v1.0/orders/{order-id}  

https://thecodebuzz.api/v1.0/orders/{order-id} 

Please note the above URL are the same for getting Order and deleting Order methods as they both deal with the same resource. Both operations will be differentiated by the Standard REST operation as specified.

Example: If using the CURL command to invoke API then the above URLs will be executed as below,

  curl GET https://thecodebuzz.api/v1.0/orders/123 

  curl PUT https://thecodebuzz.api/v1.0/orders/123

  curl DELETE https://thecodebuzz.api/v1.0/orders/123 

Use Plural Nouns

The use of plural nouns is preferred.

Example:

https://thecodebuzz.api/v1.0/orders/{order-id} 

https://thecodebuzz.api/v1.0/payments/{pay-id}  

Use Hyphen (-) in URL(preferred)

The use of a hyphen(-) improves the readability compared to other separators like underscore etc. In the case of the long name, one can use a hyphen(-).

Example

https://www.thecodebuzz.com/v1.0/books-management/north-america/orders/{order-id}  

https://www.thecodebuzz.com/v1.0/books-management/north-america/payments/{payment-id}  

Underscores (_) should be avoided in the URL

Underscores(_) are not readable and often blend with the underlines to the plain eye.

In a few servers, DNS does not allow the use of underscores(_) in the base URL.

To avoid any confusion use of a hyphen(-) instead of (_) is recommended if names are long.

Bad

https://thecodebuzz.api/v1.0/books_management/north_america/orders/{order-id} 

Good

https://thecodebuzz.api/v1.0/books-management/north-america/orders/{order-id}   

API URL Length size limitation

As per RFC 7230,

HTTP does not place a predefined limit on the length of a request-line. […] A server that receives a request-target longer than any URI it wishes to parse MUST respond with a 414 (URI Too Long) status code.

However, URL length should be in consideration as some server does not yet support URL length beyond 2048 characters.

URL length issue is mostly found in the HTTP GET method is called with large inputs. These limitations often come as surprises.

Canonical Identifier for Movable Resource

Resources that can be moved or renamed SHOULD expose a URL that contains a unique stable identifier. Often such resources can use GUID or other techniques to assign a unique identifier.

An example of a URL containing a canonical identifier is:

Example

https://api.thecodebuzz.com/v1.0/books-management/north-america/orders/123819274834875/cart

Use Versioning in the URL

If you plan to introduce breaking changes or updates in the future, consider including versioning in the URL to ensure backward compatibility.

For example,

https://www.thecodebuzz.com/v1.0/books-management

https://thecodebuzz.com/v2.0/books-management

There are various ways you can achieve API versioning. Please visit the below guidelines,

• RESTFul API Versioning Best Practices

Avoid Excessive Nesting

API URLs should focus on the resource or action being performed.

It should not expose implementation details such as technology stack, database names, or internal server structure.

HTTP Status Resource consistency

Ensure that your API URL responds with appropriate HTTP status codes for different scenarios.

Example

HTTP 200 – successful requests

HTTP 201 – successful resource creation,

HTTP 404 – resource not found

This consistency improves the predictability and usability of your API.

URL should expose Implementation Details

The URLs should not on the resource and its actions, rather than exposing the underlying implementation details or database structure. Avoid including database table names or internal implementation details in the URLs.

Additional examples

RESTful URL design for HTTP GET or Search

Get all books

HTTP GET  https://www.thecodebuzz.com/books-agencies/agencies/books

Get all books for a given agency

HTTP GET  https://www.thecodebuzz.com/books-agencies/agencies/{agency-id}/books

Get a given book for a given agency

HTTP GET  https://www.thecodebuzz.com/books-agencies/agencies/{agency-id}/books/{book-id}

One can also use query parameters for effective GET or Search,

https://www.thecodebuzz.com/api/Accounts/PersonalAccounts?employeeId=123&accountNumber=238

Please refer to here few examples,

• Pass Multiple Inputs to an HTTP GET in .NET -Guidelines

HTTP POST example

Create or Add new books

http://api.thecodebuzz.com/books-agencies/agencies/books  

HTTP PUT example

Update a given book for a given agencies

HTTP PUT http://thecodebuzz.api/books-agencies/agencies/books/{book-id} 

HTTP DELETE

Delete a book from agencies

HTTP PUT http://thecodebuzz.api/books-agencies/agencies/books/{book-id}  

Delete a given book id from a given agency

HTTP PUT http://thecodebuzz.api/books-agencies/agencies/{agency-id}/books/{book-id}  

All the above naming conventions are generic enough and can be used or extended for RESTFul services based on DDD (Domain-Driven Design) or non-DDD API or services.

References:

• HTTP GET with Request body – Guidelines

Do you have any better suggestions or inputs? Please sound off your comments below. Thanks.

Summary

The resource is prime in the REST architecture specifications, principles, and standards. It’s important that REST URIs follow a set of syntax rules and maintain the identification of resources in API. These discussed general best practices can be adapted based on the specific requirements and conventions of your API design.

---

Please bookmark this page and share it with your friends. Please Subscribe to the blog to receive notifications on freshly published(2024) best practices and guidelines for software design and development.

---