RESTful API
All right guys. I just recently satisfied my curiosity about RESTful API. And here is an extract of the knowledge I got about RESTful API.
Now the first question you might have is what exactly does REST mean and what does it mean to make an API RESTful right?
Well, rest is not resting on your comfortable couch, but it actually stands for REpresentational State Transfer which is quite a complex word to understand because it doesn't make sense. But in order to understand it, we have to backtrack a little bit and we have to go back to that classic architecture that we all must be aware of.
The client and server architecture.
And this is the architecture that the entire internet is pretty much built on. So let’s just review it quickly. So the client (PC, Smartphone, Laptop) makes a request to the server.
So what exactly is the client? Well, there are a lot of analogies for it and my favourite one is if we were in a restaurant the client would be the client who’s paying for the meal right?
And the server would be the server staff at the restaurant. So when our client makes a request saying “I’d like a pizza to please” then the server has to check to see if this is something that the restaurant can fulfil and if so he will smile graciously at you and fulfil that request.
But if the client requested something that they didn’t have for example a burger and it’s not on the menu then the server would give you an error code.
A classic one of course being 404 which is a resource that doesn’t exist. “We don’t stock burgers”. Now when the client makes that request to the server classically on the internet this is done through an HTTP request (Hypertext Transfer Protocol request).
For simplicity, HTTP is one of the languages that servers speak. Another one that you might have heard of is for example the FTP request which is the file transfer protocol request.
Now let’s say that the client has successfully made the request to the server and this is something that the server can serve up, so it sees it as a valid request instead of a 404, then in this case the server should respond with the results of what it is that you requested.
So in the restaurant that might be your pizza, but on the Internet that might be the web page HTML or resources such as images or data. So in code, you would have already seen app.get and in the callback function we’ve got our request and our result and the result is what we get back from the server. Now in order to give us that result, the server might do one of two things. It might do some computation, run some code to work out the result that you need for example if our server was a simple calculator web application, or the server might need to communicate with our database in order to grab the relevant pieces of data that the client requested.
So depending on what kind of request the client made, what kind of resource they wanted, the server might do one or both of these things.
So we’ve seen that the client has to talk to the server using an HTTP request, a specific language that the server can understand. But also there’s only a certain amount of things that the server can do right?
Say at a restaurant you would have a menu of items that this particular restaurant would serve, and it’s exactly the same on the Internet.
The server will have a whole bunch of APIs which are services that it can expose for clients to be able to tap into. And so when we’re building an API we’re kind of like building the menu of things that our server can respond to when a client makes a request. So now that we understand all three components, what does it mean to make our API RESTful?
Well REST is essentially just an architectural style. So just as you have different buildings that have different architectural styles for example, the Baroque architectural style with the nice arches or other buildings might be built in the Gothic architectural style with flying buttresses and these imposing beams. And my favourite the Neoclassical have these incredibly geometric shapes and columns that really remind you of old Greek architecture. So these are architectural styles for designing buildings.
Well REST is an architectural style for designing APIs and it’s definitely not the only architectural style.
Alternatives of REST API
So the other really really popular one before REST became the dominant style was SOAP. And there’s also GraphQL or FALCOR and there’s a lot of other architectural styles. But the gold standard for web API is REST.
So how exactly do we make our API RESTful?
Well, there’s a lot of rules that an API has to follow to be RESTful. And just as you have rules that you might follow at your workplace or your school you might have a uniform no shorts no singlets don’t smoke in the building, you will also have a whole bunch of rules for making an API RESTful.
But the two most important ones are:
1. Use the HTTP request verbs or using that HTTP request language
2. Use a specific pattern of routes and endpoint URLs.
And these two things are probably the most important parts of making your API RESTful. And we’re going to look at each of them in detail.
So first what exactly are the HTTP verbs? Well, you’ve already seen some of them like Get and Post. To make API RESTful this are the must:
- GET
- POST
- PUT
- PATCH
- DELETE.
So these are the five HTTP verbs or methods that you should be using in order to make your API RESTful. And you might realize that they have a lot of similarities to something like the database CRUD Operation (Create, read, update and delete)
So we’re going to look at our REST HTTP request verbs alongside our database CRUD functions and we’re going to see how each of these verbs work in practice.
1. Get Method
GET is basically the same as “read” in CRUD operation. So you may have already written this code many many times.
app.get('/', (req, res) => {
res.send("GET Request Called")
})
Every single time we want our server to serve up, some resource we’ve been using app.get and then we pass a callback that responds to the request and sends the result back.
And if the request involved something that relates to our database then that’s the equivalent of searching through our database and returning the data as the result.
2. Post Method
POST corresponds to the “create” word in our CRUD functions. So whenever we’ve created a form on our website we’ve used app.post() and then we have our callback with our request and response.
app.post('/', (req, res) => {
res.send("POST Request Called")
})
And when data is posted to our server then we create an entry in our database and we save that data for later. So in this case the request will contain the data and the response will simply be a success or maybe an error code if there was a problem.
3. Put and Patch Method
The next one is PUT and PATCH and they both update our database. So we might have app.put() or we might have app.patch() and these two things both go into our database and update some pieces of data.
So what is the difference between put and patch? Well here’s a good analogy. Recently I went onto Amazon and I found a really nice looking bicycle and because I really wanted to poison my lungs by exercising around London, I clicked on the buy now button. So there I was super happy super excited for my bicycle to arrive and then on the day of arrival I open up that box and my bicycle was really messed up. The whole front wheel was broken so I’m not really sure what happened at the Amazon warehouse but I got in touch with them and I wanted to try and figure out how we can solve this problem.
So there were two ways that they could fix this problem.
- They send me an entirely new bike. So this is the equivalent of Put. You’re updating your database by sending an entire entry to replace the previous one.
- Amazon offered was for them to simply send me a new tire. That was the only thing that was broken, the rest of the bike was fine and in order to save the world from carbon emissions shipping a wheel is much better than shipping an entire bicycle. And this is the same as a Patch Method. So when you’re sending a patch request to the server you’re only sending the piece of data that needs to be updated. Instead of the entire entry that will be replaced, you’ll simply just update the thing that needs to be updated.
So when we see this in practice only to think back to this bicycle analogy and maybe it’ll help you try to understand the difference between these two words.
4. Delete Method
It simply deletes and that’s the same as delete in CRUD and the code is as easy as app.delete() and this just deletes or destroys a particular piece of data in our database.
Routes and endpoints
So now that we’ve looked at the HTTP request verbs and we can see how they’re used The next thing to talk about is the specific pattern of routes and endpoints that you have to use in order to make your API RESTful.
In our server, we can specify specific routes or URLs in order to access certain resources. So you might want to see elephants on google your route or URL must be like this www.google.com/elephants that would bring up all of the elephants and if you replace any word with elephants you will be pointed towards that specific data.
So you may have used routes in Express Node in server code. But in order for our API to be RESTful we have to have a specific pattern of endpoints and routes.
So for example, if our API was the Wikipedia API right? And in our database, we had a whole bunch of articles.
Now if we created a route for articles then when a client makes a get request to /articles, it should fetch all of the articles.
And when they make a post request to the /articles route then it should create a single new article and add it to our database of articles.
And when we make a delete request to /articles then it would delete all the articles in our database.
But RESTful routing also has rules for individual resources. So within all of the articles, we will have specific articles right?
Say we had an article on Jack Bauer, then if the client was targeting /articles /jack-bauer then if they made a get request that would fetch the specific article on Jack Bauer from our database.
And you can also use put and patch to update that specific article on Jack Bauer and you can delete the specific article as well.
So now that we’ve seen how HTTP request verbs work and the pattern of routes that make your API RESTful. We pretty much got the idea of what we must follow to create RESTful API.
