All right guys.
So in this module we're going to learn all about how to build your very own RESTful API.
Now in previous modules we've seen and used APIs that other people have created.
And we've also started to build up our server to allow get requests and post requests.
But in this module we're going to do it from beginning to end and we're going to build our very own
complete 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 lazing on the couch and watching Netflix but it actually stands for REpresentational
State Transfer which is quite a mouthful
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 really looked at which is 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 makes a request to the server.
So what exactly is the client?
Well if we were in a restaurant the client would be well 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 say "I'd like a pizza please"
then the server has to check to see if this is something that the restaurant can fulfill
and if so he will smile graciously at you and fulfill that request.
But if the client requested something that they didn't have for example a sausage and it's not on the
menu then the server would give you a error code.
A classic one of course being 404 which is resource doesn't exist.
"We don't stock sausages".
Now when the client makes that request to the server classically on the internet this is done through
a HTTP request, Hypertext Transfer Protocol request.
And we've already seen this when we said app.get and then we have our callback with our request and
result that is that request.
And the analogy for this is it's kind of like the language that you're using to make the request.
Say you're saying, "I want a pizza"
right?
And if you're in France you would have to say that in French although I'm not sure what you're doing
eating pizzas in France but the server would be a to understand your request and give you back the correct
result.
Now the thing you have to remember is that HTTP, this Hypertext Transfer Protocol, is not the only
language that servers can speak right?
Another one that you might have heard of is for example the FTP request which is the file transfer protocol
request.
So if you use the wrong language you might not get back the result that you're looking for.
So for example if a server speaks French in France and you try to speak to him in Italian,
that probably won't work.
So we have to make sure we've got the right language for making our request.
Now at this point some students might say, "well what about that other thing, that HTTPs request?"
What does that stand "s" for
and is it a different language?
Well HTTPs stands for each HTTP secure request so remember that all your requests and responses are going
across the Internet and can be potentially tapped in by lots of people.
So if you wanted to make it secure so you don't want to be on a website entering your car details and
it's just going through you know a bog standard age HTTP request because somebody might hijack that along
the way and that's not very secure.
So we can also use cryptography and encrypt our request.
So if anybody does intercept the request they won't be able to know what it says.
Now this is kind of equivalent to having like a secret code language for example if both you and your
waiter speak Klingon then you could communicate securely and it doesn't matter if you're overheard in
the restaurant because nobody else will be able to understand what you're saying other than yourself
and your waiter.
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 our 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 that 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 favorite 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.
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 that's what we're going to be looking at. And REST actually came about really quite recently as a
part of this guy's PHD.
This is Roy Fielding
and he did his PHD in the University of California and as a part of his Doctorate he researched and
came up with this architectural style that we now call REST.
And it proposes a set of rules that web developers could follow when they're building their APIs.
And he came up with this idea that all websites across the web would use the same structure for building
their APIs.
I mean imagine if you had a whole street and all their buildings had the same layout, for example the
toilets for men and women are always on the same floors in the same position then you would never get
into a situation where you're trying to find the toilet.
So my personal struggles aside, essentially in his PHD, he proposed that the Internet could do the same.
If every web API was built using the same common guiding principles then it would be so easy for everybody
to work together and be able to use different APIs quickly, easily and efficiently.
So pretty neat for a PHD project right?
There's definitely some PHD projects that are a lot worse
like the guy who had to look into the propulsion parameters of penguin poop.
But maybe if you really like penguins that's OK.
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 using the HTTP request verbs,
so using that HTTP request language and also to 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.
First is GET, then there's POST, PUT and PATCH. PATCH came relatively recently in 2010 and it was added to
the HTTP request language essentially very recently.
But it's kind of a neat twist on how we update data and we're going to look at that in a little bit
as well.
And finally you've got DELETE.
So these are the five HTTP verbs 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 that we covered previously in the database
module which is when we looked into CRUD
right?
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.
So the first one is GET and GET is basically the same as read.
So we've already written this code many many times. 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 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.
The next one is POST and POST corresponds to the create word in our CRUD functions.
So whenever we've created a form on our website we've used app.poss and then we have our callback
with our request and response. 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 success or maybe an
error code
if there was a problem. 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.
Option one was they send me an entire new bike.
So this is the equivalent of put. You're updating your database by sending an entire entry to replace
the previous one.
Now the other option Amazon offered was for them to simply send me a new tire.
That was the only thing that was broken,
the rest 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 patch.
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 updating 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.
The final one is really simple.
It's simply delete 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.
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.
So just as when you go on a Safari there are different routes that you would use to reach say the elephant
area or the camels or the hippos, in our server
we can specify specific routes or URLs in order to access certain resources. So you might have
you know www.google.com/elephants then that would bring up all of the elephants and
/camels would be for the camels and hippos.
So these are routes and we've already used route before using Express a Node in our 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 the route for /articles applies to all of the 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.
Now a little bit later on when we create all of these routes using the HTTP verbs it's gonna be a lot
more clear how each of these works.
But for now I just want you to get an overview of what RESTful routing actually looks like before we
get started.
So now that we've seen how HTTP request verbs work and the pattern of routes that make your API RESTful,
the next step is to get started and actually build our very own API.
So for all of that and more, I'll see on the next lesson.