REST URL and Resource Naming Conventions Best Practices
Rest URLs refer to the resources it manipulate and thus require to follow a standard within your organization to keep it consistent across the APIs. Since the URL or URI refers to a resource, it is natural to point that to a noun instead of verb. However, there are conflicting suggestion in the industry when it comes to this.
Another point is in RESTful APIs major operations such as POST,GET, PUT, DELETE forms a CRUD ( Create, Read, Update and Delete) Use Case. Now, what are the options when it comes to operations beyond that and how to design an URI to take care of such need? Restful APIs are definitely beyond simple CRUD Use Case.
When it comes to RESTful API Design best practices, you need to have a standardization for URI and Resource name. In this article, those scenarios of URI standards and best practices will be covered.
Resource Arche Types
Rest resources has strong resemblance with Object Orientation. Drawing the simialarity the following four resource types are possible. In the book Rest API Design by Mark Masse, similar terminologies are used.
1. Object
Any single Entity, most of the times represented by an Id. Mark Masse has used the name Store for this Archetype.
myplatform.com/customers/1628
2. Collections
Collection of Objects. example:
myplatform.com/customers/
3. Association
myplatform.com/teacher/1256/class/121
Teacher with id 1256 is assigned to class 121.
4. Controllers
Controllers are procedural concept. Resources that perform actions. More details are covered in this article.
REST URL Noun or Verb
Before going in to the detail, let us consider some examples of Resources. A Customer, a Hotel Room, an Access Card etc are examples of resources. So it makes absolute sense to stick to the nouns in such cases. Developers relate Resource to the Class of Object Oriented paradigm and actions to the functions in side that class. And hence there is a strong feeling to keep everything as noun. But sometimes, it makes sense to use verb and whenever it makes absolute sense.
If you are working on a hotel API platform what a Check-In would be? Check-In could also be treated as a resource with its own properties such as time, number of guests etc. You need to make a call based on the context of your platform. and in some cases if it is possible to convert it in to a noun or associate it with some other resource, you may take that option too. The bottom line is using Verb for a resource is well accepted idea as well in the developer community. However, stick to Noun whenever possible.
Singular or Plural
It is recommended to use Plural whenever possible. However this not also a hard and fast rule based on the situation. In a Resource contains another Resource and the count of the contained resource in one and only one use may use singular. These are called singleton resources. For example, engine in a vehicle could be shown as vehicles/engine.
It must be kept in mind that URI definition is NOT part of REST specification and thus you must come up with a design that is easy to understand and usable instead of struggling to keep up with something not that important. A standard must be adopted for your API platform and make sure all APIs follow that standard.
Actions Beyond CRUD
When it comes to actions theoretically there are three options
1. Use it as part of URI - http://myservice.com/rooms/checkout
2. Use it as query parameter - http://myservice.com/rooms?action=checkout
3. User it as part of your Header - which won't be visible in the URL
Query parameter approach is discouraged in this case. We will use query parameter only to filter and sort. Two other approach could be adopted based on the need. If the action has many attributes or you want the action to be visible in the URL, use URI approach. With this approach, if weblogs are analyzed, action will be visible there. In other situations use Header approach. Here you give all focus to the resource and treat action as something working on it.
Since this action will be NON idempotent, the Method should be POST.
REST API Filters and Sort
It is recommended to use query parameters for REST API Filters and Sort.
REST URI Naming Convention and Examples
Here is the summary of Naming conventions
1. To create a customer
2. To update a customer with customer id 198
3. To read a customer with id 198
4. To delete a customer with id 198
5. Any action should be part of URI, if the action itself has attribute and thus a controller. Otherwise use Header to show action
ie, to Check-in a customer to the hotel
or
6. Use Noun for Resources whenever possible
7. Use Verb only if it absolutely makes sense and to show a Controller Resource
8. Use plural for the Resources whenever possible
9. Use Singular only in case of Singleton Resources
myplatform.com/customers/access-card
10. Use Query Parameter for filter and sort
myplatform.com/rooms?reservation-date=12-01-2021&order-by=room-number
11. Arrange order of the URI to show resource hierarchy
myplatform.com/rooms/beds
12. Show version number in the URI. Any only use major version number in the URI
myplatform.com/v1/rooms
13. Make sure GET,PUT and DELETE are idempotent. POST is non Idempotent.
14. Use comma separation to show multiple resource Ids
15. Use lower case and dashes in stead of Camel case or under scores
access-cards instead of accessCards or access_cards
16. Do not abbreviate the end point
Use
access-card instead of acc-crd
17. Use well known generic name instead of a jargon
use access-card instead of swipe-card
18. Do not use trailing slash
use URL of the form http://myplatform.com/resource
19. Use American English
Just a matter of standardization recommendation, stick with American English in spelling
Wrapping it Up
There is no consensus in RESTful API resource naming and URI end points. However, It is important to have a standard for your API platform to keep consistency. There are many debates when it comes to resource naming approaches. The recommendation, best practices and examples given in this article will give you a good foundation for your Rest API resource URI standardization.