REST is a set of guidelines that explains how the client and server should communicate with each other. REST stands for Representational State Transfer. Any application programming interface (API) that follows the REST design guideline is considered RESTful.
In order to get the most out of this article, a foundational understanding of Internet Networking and HTTP (Hypertext Transfer Protocol) would be preferred.
A typical modern application has two primary components: the frontend and the backend. Frontend is basically what you see on your screen. Backend handles and stores data sent to it by frontend into the database. REST is mainly used in developing the backend side of applications. It is also the de facto standard for public facing APIs.
For example, let’s imagine that you are using your favourite social media app to search for one of your friends. You open your app, type ''John Doe'' in the search field, press enter and you see a list of people with that name. When you press enter, your app requests data from an API on the application's server. When you see the users appear on your screen, the API has returned the relevent data and completed the request.
Now that we know how REST API’s work conceptually. Let’s discuss how they are used in practice, starting with API endpoints.
An API Endpoint is a digital location, typically a uniform resource locator (URL) that provides the location of a resource on the server. Resources are data sets that an API allows you to work with, and which are accessible via endpoints. In order to access specific records from a resource an item is passed in an endpoint which is basically an unique identifier.
For Instance, This is how an endpoint, resource and an item looks like.
What are HTTP verbs?
HTTP defines a set of request methods to indicate the desired action to be performed for a given resource. Most of the HTTP requests are in the verb form, hence these request methods are sometimes referred to as HTTP verbs.
All resource names in your REST API’s should be plural. If we wanted to get a list of posts or to delete a specific post, we would make a request to the posts resource.
For example:
DELETE: /posts/acs415cc1c2
GET: /posts
This format clearly indicates that there are not just one but many posts and we are looking for a post with a specific id and performing an action on that post.
Let’s take a look at what endpoints look like when they don’t follow this rule.
DELETE: /post/acs415cc1c2
PUT: /post/acs415cc1c2
GET: /post
The above Endpoint might be acceptable to delete a post or to update a post, however If I want to get a list of posts, the convention is to make the request to just the resource name. In this case that would be singular which obviously doesn't make sense. One would assume that that endpoint would return a single post.
If you don't use plural nouns, the "give me a list" endpoint convention doesn't work, hence we should use plural nouns.
Verbs should not be used in the endpoint routes when creating a REST API. The endpoints should use nouns, signifying what each of them does. Commonly used HTTP methods such as GET, POST, PUT, PATCH, DELETE are already in verb forms to execute basic CRUD operations. In other words, leave the work on HTTP verbs and let them tell what an Endpoint does exactly. So, data would be retrieved using GET, created using POST, updated using PUT and PATCH, and deleted using DELETE.
So when you want to create an endpoint for creating a post, It should not look like this:
POST: /createPosts
Instead, it should be like this:
POST: /posts
Our backend applications can get very complex and it is a possibility that we might need to perform an action on not just one but multiple collections. In this case, you should nest them in the hierarchy.
Now let’s assume you want to delete or update a comment on a specific post. In this case you have a post table and comment table with one to many relationships between them. So you will have a postId as well as a commentId where comments won’t exist without a post. You should design your endpoint indicating the relationship between them. The parent entity first and the child entity below it, for example:
PUT: /posts/acs145cc1c2/comments/5s4a5wee5cd2e
This endpoint clearly says that we are performing an action on a specific comment which belongs to this specific post. Nesting that is deeper than three levels should be avoided because it can make the API less clear and readable.
You should always respond to API requests with standard HTTP status code so that users can know what exactly is going on with their request. Whether the API has returned a response successfully or it failed. And if it failed, what was wrong with it?
HTTP Cats is a fun and easy way to learn about what each HTTP status code means and does.
At Moonward we apply the highest standards when designing our APIs, because they are crucial to the success of our products. We build highly functional applications that not give users an incredible user experience, but are secure.
If you're looking for experts on mobile app development, you're in the right place. Book your free 30-minute strategy call now!
.svg)
.svg){kind=logo}
