Let’s say the mobile team or the front-end team comes to us and asks for some APIs to get the dynamic data from the backend.
What do we do?
I mean, of course, we would ask for the requirements, right? Like what data they would want and what would be the methods, how we would return the response, and so on.
And then the million-dollar question is to decide the endpoints right?
Well, that would have been the million-dollar question if we don’t know about RESTful APIs or REST Framework.
So in general what we are looking for are CRUD APIs. But what is CRUD?
What is CRUD?
CRUD Stands for
- C => Create
- R => Read
- U => Update
- D => Delete
We usually need CRUD APIs in order to do most of the common operations in our database on the server. So more or less we would be spending our time implementing these CRUD APIs and then some additional functionalities on top of it or may need some custom complex handling of the request might be needed as well.
Let’s see an example and understand REST APIs.
A note-taking app
So, what all APIs we might need?
Endpoint to do the below operations, notably to:
- List the notes
- Get any specific note
- Create a note
- Update a note
- Delete a note
We are going with a very simple app and won’t be going very deep into the minute details.
If we have to make the endpoints how will we make them?
I won’t go into the definitions, you can find them already on the internet, won’t you? I feel an example with an explanation is way more helpful than the other.
But before that let’s revise the basics.
HTTP verbs
GET
The GET method, as the name suggests should be used to get something.
POST
The POST method is used to submit an entity for a specific resource. Often when this request is made there are some side effects, such as inserting some data into the database.
PUT
In the PUT method we update everything related to a specific resource with the data send in the request body.
PATCH
In the PATCH method we modify a resource partially. So for example, if we are updating a note as in our case with a PUT request we would send the whole note data in the request body.
But what if we only wanted to update the title of the note?
I mean yes, we can send the whole body with the only difference that the title would be the new title in the request body.
But it would be expensive right? The request body would be bigger. What if we can only send the data that we want to update and the rest that we don’t send can stay that way?
Here comes the PATCH request, where we only send the fields in the request body that we want to update.
DELETE
When we want to delete a resource we use DELETE request.
We still have a bunch of different HTTP request types or HTTP Verbs you may read about them in the MDN Docs.
REST API Endpoints
List Notes
GET: /notes/Notice two things, the HTTP Verb and the endpoint or the route.
In the above case, the HTTP Verb is GET and the endpoint is /notes/
The important this is the /notes/ it may have any prefix such as https://example.com/resources/notes or https://example.com/notes it does not matter. What matters is the suffix which in this case is /notes and we will talk about it.
So notes should be notes only and not note as while creating the REST Endpoints, we use the plural form and not the singular form. Hence, note it would be notes and respectively for any other resources too. For example, /accounts/ , /receipts/ , /posts/ etc are the valid ones.
Back to the topic, if we want to get a list of all the notes we would make a GET request to the /notes endpoint.
Get a specific Note
GET: /notes/:slug/The method would still be GET only in the endpoint, we would append the :slug of that specific resource on the listing resource endpoint.
:slug can be anything, which should be able to uniquely identify that resource. It can be the primary key of the resource or just the slug field of the resource.
Create a Note
POST: /notes/Whenever we make a POST request to the same /notes/ endpoint we mean to create a new Note.
Update the whole Note
PUT: /notes/:slug/Send the whole resource body in the request and it will replace the resource with the data send in the request body. Note, that we have to pass :slug in the request endpoint. Denoting which resource we want to update. i
Partially update a Note
PATCH: /notes/:slug/Partially update any given resource, it is similar PUT but we only have to send the fields in the request body that we want to update. We have discussed this above.
Delete a Note
DELETE: /notes/:slug/We just need to make the method the DELETE and make sure the :slug identifies the correct identifier.
REST API Status Codes
So the above endpoints combined with the standard status code in every response would make a perfect REST API.
Quick Recap
- 2xx: Successful Response
- 3xx: Redirection Message
- 4xx: Client-Side Error
- 5xx: Server-Side Error
2xx: Successful Response
Return with 2xx status code if the request was a success.
3xx: Redirection Messages
You might have noticed that sometimes we redirect users to a different endpoint, these status codes are helpful in denoting that.
4xx: Client-Side Error
Whenever we have some error from the user side, we respond with the 4xx. For example, in the above example if the user sends :slug that is not valid and we are not able to identify any unique resource we must respond with 404 status code.
If any of the endpoints need authentication and we don’t get the user token/cookie (with whatever means we would identify the user) we would respond with 401
If the user is authenticated but they don’t have the required permissions we would respond with 403
5xx: Server-Side Error
When something goes sideways from our side, we respond with the 5xx
You can read more about the status codes here in the MDN docs.
Closing Remarks
REST Endpoints are a combination of the above two guidelines. And the important point to note is that these are just the guidelines. Meaning, if you implement some other ways, your server won’t crash.
But it is good to follow them, isn't it?
Comments