Best Practices for Designing RESTful URIs
When designing RESTful URIs, focusing on noun-based resource naming and consistency is crucial for creating a well-structured and intuitive API. Let’s discuss…….…….…….…….
What is REST?
REST stands for Representational State Transfer. It’s an architectural style for designing networked applications. RESTful systems often use HTTP requests for performing CRUD (Create, Read, Update, and Delete) actions on resources. These resources are often identified using URIs (Uniform Resource Identifiers).
URI (Uniform Resource Identifiers)
In a REST API, URIs play a significant part in identifying and routing resources. URIs are used to address API-exposed resources. When resources have proper names in URI, an API becomes natural and simple to use. If not implemented correctly, the same API can be difficult to operate and understanding. The limitation of a uniform interface can be partially fulfilled by combination of URIs and HTTP verbs and using them in line with the standards and conventions.
What is a Resource?
In REST, the fundamental information representation is known as a resource. Having a consistent and comprehensive REST resource naming procedure will be one of the most beneficial design decisions in the long term.
A resource is defined as any piece of information or item that can be accessed and manipulated using a URI and represented in a variety of forms.
Example :- Events, Products, Orders, Articles, Customers
Singleton and Collection Resources
A resource can be a singleton or a collection.
Example : “books” is a collection of resources and “book” is a singleton resource (in a Library domain).
We can identify “books” collection resource using the URI “/books“. We can identify a single “book” resource using the URI “/books/{id}“.
Collection and Sub-collection Resources
There are collections and sub-collection of resources.
For example, sub-collection resource “accounts” of a particular “users” can be identified using the URN “/users/{userId}/accounts” (in a user management domain).
One user has multiple accounts.
Below shows the hierarchy of above scenario:
Best Practices followed when designing a URI
1. Use nouns to represent resources
RESTful URIs should refer to a resource that is a thing (noun) rather than an action (verb), because nouns have properties that verbs do not, and resources have attributes.
Examples: Teacher (Teacher has a name, id, age, qualifications etc.), Apple (Apple has a color, taste, expiry date etc.)
Below show some designs of URIs using resources.
Incorrect (Action-based):
For more clarifications Resources divides into 3 main categories. They are
Document
A document resource is an individual object instance or database record.
In REST, we consider a single resource within a collection. Use the “singular” name to denote the document resource archetype.
Collection
A collection resource is a server-managed directory of resources.
Here a collection resource has the permission to choose whether to create a new resource or not and to choose wants to contain and also decides the URIs of each contained resource
Use the “plural” name to denote the collection resource archetype.
Store
A store is a client-managed resource repository. A store resource allows an API client to store resources, retrieve them, and decide when to remove them.
A store never creates new URIs. Instead, each saved resource is assigned a URI. The URI was chosen by a client when the resource was initially put into the store.
Use “plural” name to denote store resource archetype.
2. Consistency is the key
Use consistent resource naming conventions and URI formatting to minimize uncertainty and maximize readability and maintainability.
Use forward slash (/) to indicate hierarchical relationships
Used in the URI’s path to denote a hierarchical relationship between resources.
Do not use trailing forward slash (/) in URIs
Avoid using a forward slash (/) at the end of a URI as it adds no semantic value and may confuse the URI.
Use hyphens (-) to improve the readability of URIs
To make your URIs easy to understand, use the hyphen (-) character to improve the readability of names in long-path segments.
Do not use underscores ( _ )
It’s possible to use an underscore in place of a hyphen to use as a separator. But with the application’s font, there’s some possibility that the underscore (_) character can either get partially hidden or completely hidden in some browsers or screens.
To avoid this confusion, it’s recommend to use hyphens (-) instead of underscores ( _ ).
Use lowercase letters in URIs
When convenient, lowercase letters should be consistently preferred in URI paths.
3. Do not use file extensions
File extensions look bad and do not add any advantage. And no reason to keep them.
4. Never use CRUD function names in URIs
We should not use a URI to demonstrate a CRUD function. URIs are simply used to identify resources and do not allow for any unique actions on them.
We should use HTTP request methods to indicate which CRUD function is performed.
5. Use query component to filter URI collection
Often, there will be some requirements where we need to sort, filter, or limit resources from a collection with a specific resource attribute.
For this requirement, we can use a query parameter with resource collection API instead of creating new API.
Do not Use Verbs in the URI
It is not appropriate to use verbs in REST URIs as REST uses nouns to represent resources, and HTTP methods (GET, POST, PUT, DELETE, etc.) to perform actions on those resources.
In cases, where we need to perform some action that does not apply naturally to the definition of resources, we can create the custom URIs that can be considered nouns/resources and perform an action over them.
Reference
Thank you!