RESTing: Part I - Resources and API Naming Convention

Anuja Dalal
Oct 30, 2022
6 min read

Updated: Sep 15, 2023

As we have created a web of digital connections around us to improve our world, we consciously or unconsciously use API calls (Application Programming Interfaces). For instance, imagine a Friday evening when you ordered pizza 🍕 using an app on your phone, then received a text message confirmation, and started tracking your delivery on Google Maps. You also received a text from your bank notifying you that the payment for your pizza had been made. In the meantime, you've started watching a movie on NETFLIX, but of course only after updating your Facebook status first. During this typical Friday evening, so many API calls are made, in reality, at every step when you are trying to make your Friday relaxing you were doing API calls.

The usage of APIs is inevitable with modern-day technology. In the API paradigm REST is one of the popular and regularly used design patterns we will cover in this blog. REST is not something new for developers. Yet I have seen developers ignore best practices while following them. Although we are not going to get into the microscopic details of REST and believe our readers are having basic knowledge of REST with this and the coming blogs for the RESTing sequel, we will see some quick guidelines for designing endpoints, HTTP responses and finally when to say API is Restful. In this blog, we will see designing API endpoints (the other two topics will be followed in upcoming blogs).

What is a REST?

Cannot start without the mention of Roy Fielding. Representational state transfer (REST), in 2000, Roy Fielding introduced REST to the world as an architectural style. REST makes communication within the system easier.

The basic operations REST is going to provide are CRUD functionalities (Create, Read, Update and Delete) of resources. Every developer does this after he gets the hang of "Hello World"!

API provides URLs, that can be used to manipulate resources. I felt it is important to identify these resources in the first place, before considering API URLs (or naming conventions). When developers fail to identify resources, they end up creating endpoints that do not adhere to guidelines.

Example of incorrect naming convention - API call to find authors who are actively writing -

POST    /authors/search?active=true

This example uses the incorrect HTTP method POST instead of GET and it uses the resource name "search" which does not sound like a resource. So what is a resource -

What is a Resource?

Technically resource is the primary unit in REST that represents an abstract or real-world object and they are represented as nouns. Everything that can be created, read, updated, and deleted on the Web is a resource for REST, ex: any record, document, image, or object. In the above URL, the author is a resource.

Let's consider this real-world inspiring story (of an unnamed philosopher) and try to find resources that will be managed with REST.

"To reignite the love for reading, somewhere in the Mediterranean city, the 32-year-old veteran is encouraging people of his country to start therapeutic reading. This wise man created a wooden kiosk and named it after his book "Wisdom Seller". He loaded it with thousands of books. He kept loading new inspiring books onto his kiosk. He also uploaded inspiring short stories and articles to his kiosk. Located near the glittering sea, he provided perks in the form of free coffee for readers who finished 15 pages at least. An inspiring story to remind us that there is a part of the world where reading is considered a luxury."

Imagine as a developer you want to build an app that will allow you to upload books or articles, open those books on the kiosks and maintain a list of perks for the week and do some more similar activities. Can you recognize the resources in the above story if you want to create an app? Let's try...

Resources	Yes/No/May be	Why?
Books	Yes	Can be created, read, updated, and deleted from the app on your kiosk
Publishers	Yes	Can be created, read, updated, and deleted from the app on your kiosk
Newspapers and magazines	Yes	Can be created, read, updated, and deleted from a kiosk
Visitors	May be	If you want to save and maintain information for some good reason
Location near sea	No	Address as a resource would be better choice but kiosk being singular its address will not be maintained
Kiosk	No	Need to create or edit or delete kiosk is not a regular requirement. No Kiosk no resources.
Favourite Books	Maybe	Abstract but can be created, read, updated, and deleted
Perks	Yes	Abstract but can be created, read, updated, and deleted
Guest Lectures	Yes	Can be created, read, updated, and deleted
Search	No	Searching is functionality not the resource. The resource is a noun.
Create/ Edit/ Delete	No	These are functionalities, not resources. The resource is a noun.

So what do you think is a resource?

Once the resources are decided for our system's second step is to manage these resources and decide their representation like JSON, HTML, YAML, plain text or XML. Our server should be able to give functionality to manage these resources. Ex: functionalities to create entries for new books or edit the list of perks.

The server manages resources and one or more clients request the resources. In the above story, the client was an application installed in Kiosk. It is possible that the same resources could be used by another client application installed in some library or somewhere in the form of a website. In order to access these resources on the server, we need some kind of address. The client applications can use these addresses to create, read, update or delete the resources.

This address of a resource is called an endpoint or API URL and it opens a new chapter for discussion, how to phrase these URLs or how to design these endpoints? The answer is - by following the REST APIs naming convention.

What is a REST API Naming Convention?

So we now know, in the REST world, the resources are nouns and require a uniform address or location over the web. In tech terms, we call them Uniform Resource Identifiers (URI) or Uniform document Identifiers or Uniform Resource Locator (URL) or simply endpoints. Creating clean URIs is a REST API Naming convention. And to its basic nature, it is nothing but an address of resource.

Creating specific endpoints for resources offers consistency, search-ability and transparency to APIs.

Finding Resources in URI

When we focus on a smaller part within this URI that provides some service we call it the endpoint. (That means we are not touching the anatomy of URLs but we will focus on part of it)

Our resources are authors, books, publishers, etc, so our endpoint should look like this -

 /authors/books 
 or /books
 or /visitors/perks 
 or /visitors/addresses

Recommended Conventions

Use Nouns and Not verbs

The first rule for naming resource APIs is resources should be nouns because they are nouns. In fact, they should be unabridged nouns. Just like in our example where authors, books, and perks are resources.

Question - So how will our endpoint look like when we want to provide a service to create, read, update or delete a book?

Which one is right 🤔 -  
/books or /createBook or /updateBook or /deleteBook

Create, update or delete are verbs so it is not recommended to use them in the endpoint. Instead, just noun is enough and REST methods are used to differentiate the CRUD functionality (Create, Read, Update and Delete). In other words, all operations can be performed through just one endpoint /books. By that said -

GET     /books        (to retrieve all books)
GET     /books/{id}   (to retrieve book with given id)
POST    /books        (to create book)
PUT     /books/{id}   (to update book with given id)
PATCH   /books/{id}   (to partially update book with given id)
DELETE  /books/{id}   (to delete book with given id)

Use Plural Nouns

In the above example, all our CRUD endpoints (GET, POST, PUT, DELETE) for books were plural. This is not only recommended practice but it makes API intuitive. In our above example, even though we were creating a single book our endpoint was-

POST    /books        (to create a book)

This tells that this endpoint has the capability to manage all books. How you want to manage will be decided by the REST method (GET, POST, PUT or DELETE in our case).

When we wanted to retrieve a single book still use -

GET     /books/{id}   
(from all the books, retrieve the book with the given id )

This tells that out of all books, I am interested in receiving details of the book with the given id. The path parameter "{id}" being in brackets "{}" suggests that its value is varying and it is optional. When it is missing the GET point will yield details of all books.

GET     /books        (to retrieve all book)

URI Hierarchy

Two resources if they are related should be separated by "/" and their hierarchy should be from left to right. If there is a path parameter like"{id}", it should correspond to its predecessor. Example diagrammatic representation of hierarchy of authors and books can be -

To GET all the books for a given author (id) endpoint will look like

GET  /authors/{id}/books  
(Retrieve all books for the author with the given id)

While following endpoints are not recommended -


GET /books/authors/{id}  
(Reverse hierarchy, from specific to generic)


GET   /books/{author-id} 
(Incorrect APIs where id is not intuitive)

GET  /{author-id}/authors/books 
(Incorrect APIs where id is not intuitive)

Question - How to represent subscriptions for web articles?

/authors/articles/subscriptions
/authors/{id}/articles/{article-id}/subscriptions
/articles/{id}/subscriptions
/articles/{id}/subscriptions/{subscription-id}/users

As per convention, all are right. Nested resources improve readability and display the relationship between resources. But it can also lead to the problem of creating potentially long URLs or redundant URLs. To avoid this some inter-team guidelines should be established that will state the level of nesting. Ex: There should not be more than 3 level of nesting.

That will force us to answer the above question in the following way -

GET         /articles/{id}/subscriptions
POST        /articles/{id}/subscriptions
PUT         /articles/{id}/subscriptions
DELETE      /articles/{id}/subscriptions

Naming our resources in unformed way is also called as Uniformed Interfaces.

Use Lowercase and Spinal case

By now we are sure resources should be lowercase words. But there are times when the resource is made up of 2 words. Example - line items, purchase orders. In such a situation, it is recommended to use a spinal case. Ex: line-items or purchase-orders .

GET     /books/{id}/purchase-orders
GET     /books/{id}/purchase-orders/{order-id} 
POST    /books/{id}/purchase-orders
PUT     /books/{id}/purchase-orders/{order-id} 
DELETE  /books/{id}/purchase-orders/{order-id}

Summary

URIs following naming conventions:

    * /books
    * /books/{id}/publishers
    * /publishers/{id}/emails
    * /article-subscriptions

URIs NOT following naming conventions:

    * /Author           
    (No upper case character and no singular)
    
    * /authors/search?active=true
    (No verb. Preferred - /authors?active=true)
    
    * /authors/{id}/msg 
    (Abbreviation not accepted)
    
    * /authors/{id}/accounts/{account-id}/payments 
    (Try to 2-level level hierarchy preferred - 
     /accounts/{id}/payments )
    
    * /emails4members*   
    (No special characters)
    
    * /memberPayments    
    (No camel case)
    
    * /phones/{id}/authors 
    (Do not go from specific to general, vice-versa is good - 
    /authors/{id}/phones. )