‫So now that we know what Express is,
‫we're almost ready to start building our API.
‫But before we do that,
‫I need to quickly talk about APIs on a higher level,
‫and more importantly,
‫introduce you to the REST Architecture
‫which is the most used API architecture today.
‫This way, we will actually know what we're building.
‫So it's extremely important to understand the stuff
‫in this video before moving on,
‫so that we actually know what we're building
‫throughout the rest of the course.
‫First of all,
‫API stands for Application Programming Interface
‫and on a very high level,
‫it's basically a piece of software that can be used
‫by another piece of software
‫in order to allow applications to talk to each other.
‫We have actually talked about APIs before,
‫more specifically, web APIs,
‫where we simply built an app that sends data
‫to a client whenever a request comes in.
‫Imagine we have our app running on a server
‫and we have a client.
‫So in fact, we effectively have two pieces of software
‫talking to each other, right?
‫And this is the kind of API we will build in this course.
‫And I guess it's the most widely used type of API out there.
‫But in fact, APIs aren't only used to send data,
‫and aren't always related to web development or JavaScript.
‫The application in API can actually mean
‫many different things as long as the piece of software
‫is relatively stand alone.
‫Take for example,
‫the Node File System, or the HTTP Modules.
‫We can say that they are small pieces of software
‫and we can use them,
‫we can interact with them by using their API.
‫For example,
‫when we use the readfile function from the FS Module,
‫we are actually using the FS API.
‫And that's why you will sometimes hear the term node APIs.
‫And that usually simply refers to the core node modules
‫that we can interact with.
‫Or when we do DOM manipulation in the browser,
‫we are not really using the JavaScript language itself,
‫but rather, the DOM API that the browser exposes to us,
‫so it gives us access to it.
‫Or even another example,
‫let's say we create a class in any programming language
‫like Java and then add some public methods
‫or properties to it.
‫These methods will then be the API of each object
‫created from that class because we're giving
‫other pieces of software the possibility
‫of interacting with our initial piece of software,
‫the objects, in this case.
‫You see, API has actually a broader meaning
‫than just building web APIs.
‫Alright? Anyway, a web API is what's most important
‫for us in the context of note.
‫Let's now take a look at the REST Architecture
‫to build APIs.
‫REST, which stands for Representational States Transfer,
‫is basically a way of building web APIs in a logical way,
‫making them easy to consume
‫because remember, we build an API for ourselves
‫or for others to consume, okay?
‫We want to make the process of actually using the API
‫as smooth as possible for the user.
‫Now, to build RESTful APIs,
‫which means APIs following the REST Architecture,
‫we just need to follow a couple of principles.
‫First, we need to separate our API into logical resources.
‫These resources should then be exposed,
‫which means to be made available
‫using structured, resource-based URLs.
‫To perform different actions on data
‫like reading or creating or deleting data,
‫the API should use the right HTP methods and not the URL.
‫Now, the data that we actually send back to the client
‫or that we received from the client
‫should usually use the JSON data format,
‫where some formatting standard applied to it.
‫Finally, another important principle of REST APIs
‫is that they must be stateless.
‫So this is a very broad overview.
‫Let's now start talking about these principles
‫one-by-one starting with resources
‫and using the Nators API that we're gonna build
‫in this course as an example here.
‫The key abstraction of information in REST is a resource,
‫and therefore all the data that we wanna share
‫in the API should be divided into logical resources.
‫Now, what actually is a resource?
‫Well, in the context of REST,
‫it is an object or a representation of something
‫which has some data associated to it.
‫For example,
‫tours, or users, or reviews in the case
‫of the example that we are following.
‫So basically, any information that can be named
‫can be a resource, alright?
‫It just has to be a name, though, not a verb.
‫Now, we need to expose,
‫which means to make available,
‫the data using some structured URLs
‫that the client can send a request to.
‫For example, something like this.
‫This entire address is called the URL
‫and this /addNewTour is called an API Endpoint.
‫Our API will have many different endpoints
‫just like this fictional endpoints that I have here,
‫each of which will send different data back to the client
‫or also perform different actions.
‫Now, there's actually something very wrong
‫with these endpoints here because they really don't follow
‫the third rule which says that we should only use
‫the HTTP methods in order to perform actions on data.
‫So, endpoints should only contain our resources
‫and not the actions that can be performed on them
‫because they will quickly become a nightmare to maintain.
‫How should we use these HTTP methods in practice?
‫Well, let's see how these endpoints
‫should actually look like starting with /getTour.
‫So this /getTour endpoint is to get data about a tour.
‫And so we should simply name the endpoint /tours
‫and send the data whenever a get request
‫is made to this endpoint.
‫So in other words,
‫when a client uses a GET HTTP method
‫to access the endpoint.
‫And just like this,
‫we only have resources in the endpoint
‫or in the URL and no verbs because the verb
‫is now in the HTTP method, right?
‫And by the way,
‫it's a common practice to always use the resource name
‫in plural which is why I have /tours here and not /tour.
‫Now, the convention is that when calling that endpoint,
‫we get back all the tours that are in a database, okay?
‫But if we only want the tour with one I.D.,
‫let's say seven, we add that seven after another slash
‫or in a search query.
‫Or it could also be the name of a tour instead of the I.D.,
‫or some other unique identifier.
‫The detail doesn't really matter at this point, alright?
‫Later, I will show you how easy it is to actually implement
‫this kind of logic with Express
‫because this is actually where Express really shines.
‫The first HTTP method or verb
‫that we can respond to is GET
‫and it's used to perform the Read operation on data.
‫Next stop, if the client wants
‫to create a new resource in our database,
‫in this example, a new tour,
‫the POST method should be used.
‫So we learned earlier that a POST request can be used
‫to send data to the server,
‫and so it makes sense to use POST
‫in order to create new resources, right?
‫Now in this case, usually no I.D. will be sent
‫because the server should automatically figure out
‫the I.D. for the new resource.
‫Anyway, what's really important to note here
‫is how the endpoint name is the exact same name as before.
‫The only difference is really the HTP method
‫that is used for the request.
‫If the /tours endpoint is accessed with GET,
‫we send data to the client.
‫But if the same endpoint is accessed with POST,
‫we expect data to come in with a request,
‫so that we can then create a new resource
‫on the server side.
‫So that is really the beauty of only using HTTP methods
‫rather than messing with verbs in endpoint names.
‫Again, it would really become unmanageable very quick.
‫Alright, next, there should also be
‫the ability to update resources.
‫And for that,
‫either a PUT or a PATCH request
‫should be made to the endpoint.
‫The difference between them is that with PUT,
‫the client is supposed to send the entire updated object,
‫while with PATCH,
‫it is supposed to send only the part of the object
‫that has been changed.
‫But both of them have the ability
‫to send data to the server.
‫A bit like POST, actually, but with a different intent.
‫So POST is to create a new resource,
‫while PUT or PATCH are used
‫to update an existing resource
‫and so it then makes all the difference.
‫And finally, to the litter resource,
‫there is the DELETE HTTP method.
‫Again, the I.D. or some other unique identifier
‫of the resource to be deleted
‫should be part of the URL.
‫Now, usually, in order to actually be able
‫to perform this kind of request,
‫the client must be authenticated.
‫So basically, log into your app, okay?
‫But that is, of course, a topic for much later.
‫So these are the five HTTP methods
‫that we can and should respond to
‫when building our RESTful APIs
‫so that the client can perform
‫the four basic CRUD operations.
‫So CRUD stands for Create, Read, Update and Delete.
‫And you will see this term all the time
‫related to APIs and database stuff.
‫And you see that these HTTP methods
‫map quite nicely to the basic CRUD operations.
‫Now, there might be actions that are not CRUD,
‫and in that case,
‫we just need to get creative with our inputs.
‫For example,
‫a log in or a search operation,
‫these are not really related to a particular resource
‫and they're not CRUD operations either,
‫but we still can create endpoints for them.
‫For example, like /login or /search.
‫But we'll talk more about these cases later in practice.
‫And just to finish this part now,
‫remember that we had two other crazy endpoint names
‫in the last slide which kind of involved
‫two resources at the same time, right?
‫And that's also no problem at all with REST.
‫So, /getToursByUser can simply be translated
‫to /users/tours,
‫in this case, user number three.
‫So this particular endpoint here
‫could send data about all the tours
‫that user number three has booked.
‫Makes sense?
‫Or in the case of deleting,
‫there could be a delete request to the same
‫or a very similar endpoint,
‫requesting tour number nine to be deleted
‫from user number three, okay?
‫So there really are a tons of possibilities
‫of combining resources like this.
‫But of course, we don't have to implement
‫all these combinations in our API.
‫We only implement what makes sense
‫in the case of our application
‫and the client that wants to consume our API.
‫So, this is how we make use of HTTP methods
‫to build user-friendly and nicely structured URLs
‫that are easy and logical to consume for the client.
‫Now, about the data that the client actually receives,
‫or that the server receives from the client,
‫usually, we use the JSON Data Format.
‫And so let's briefly learn what JSON actually is
‫and how to format our API responses.
‫JSON is a very lightweight data interchange format
‫which is heavily used by web APIs
‫coded in any programming language.
‫So it's just not related to a JavaScript.
‫And it's so widely used today
‫because it's really easy for both humans and computers
‫to understand and write JSON.
‫So you're probably already noticing that JSON
‫looks a bit like a regular JavaScript object, right?
‫With all these key-value pairs.
‫There are, however, some differences,
‫and the most important one is that all the keys
‫have to be strings.
‫It's also very typical for the values
‫to be strings as well but they can be other things
‫like numbers, true or false values, other object,
‫or even arrays of other values.
‫It's quite straighforward, actually.
‫And from this example,
‫you can kind of see how some typical JSON might look like.
‫Let's say that this is a data that we have in our database
‫for a GET request to this URL
‫so the tour with I.D. of five.
‫Now, we could send it back like this to the client,
‫but we usually do some simple response formatting
‫before sending.
‫There are a couple of standards for this
‫and we're gonna use a very simple one called Jsend.
‫We simply create a new object,
‫then add a status message to it
‫in order to inform the client whether the request
‫was a success, fail or error,
‫and then we put our original data
‫into a new object called Data, okay?
‫And we can develop this even a bit further
‫but this is really the simplest way
‫of formatting with Jsend.
‫And just, by the way,
‫wrapping the data into an additional object
‫like we did here is called Enveloping,
‫and it's a common practice
‫to mitigate some security issues and other problems.
‫Also, there are other standards
‫for response-formatting that you can look into,
‫like Jsend:API or the Odata JSON Protocol.
‫Alright, and finally,
‫a RESTful API should always be stateless.
‫So, what does stateless actually mean?
‫Well, in a stateless RESTful API,
‫all state is handled on the client
‫and not on the server.
‫And state simply refers to a piece of data
‫in the application that might change over time.
‫For example,
‫whether a certain user is logged in
‫or on a page with a list with several pages,
‫what the current page is.
‫Now the fact that the state should be handled
‫on the client means that each request must contain
‫all the information that is necessary to process
‫a certain request on the server, alright?
‫Does that make sense?
‫So, the server should never ever have to remember
‫the previous request in order to process
‫the current request.
‫Let's take the list with several pages as an example.
‫And let's say that recurrently on page five
‫and want to move forward to page six.
‫So we could have a simple endpoint called /tours/nextPage
‫and submit a request to it, right?
‫But the server would then have to figure out
‫what the current page is and based on that
‫send the next page to the client.
‫In other words,
‫the server would have to remember the previous request.
‫It would have to handle the state server side
‫and that is exactly what we want to avoid
‫in RESTful APIs, okay?
‫Instead, in this case,
‫we should create a /tours/page endpoint
‫and paste the number six to it
‫in order to request page number six.
‫This way, we would then state on the client
‫because on a client,
‫we would already know that we're on page five
‫and so all we had to do is to just add one
‫and then request page number six.
‫So the server doesn't have
‫to remember anything in this case.
‫All it has to do is to send back data
‫for page number six as we requested.
‫And by the way, statelessness and statefulness,
‫which is the opposite,
‫are very important concepts in computer science
‫and application design in general.
‫So, it's a good idea to actually have some understanding
‫what a stateless API is and how it works.
‫Anyway, this was a huge lecture,
‫but also one of the most important ones.
‫I cannot stress that enough and I actually think
‫that you can see that, right?
‫Anyway, let's now finally get back to our code.