What is a RESTful API?
An application programming interface, or API, is a way for two computers to talk to each other. Using an API is just like using a website in your browser, but instead of clicking buttons and filling out forms, you write code to explicitly request data from a server. For example, we could visit the NASA website to look at asteroids, or we could use their REST API to request the raw JSON data that is shown on the screen.
Now, most APIs in the world are RESTful, which means they follow a set of rules or constraints known as Representational State Transfer, which has been the de facto standard for API development since the early 2000s. A RESTful API organizes data entities, or resources, into a bunch of unique URLs—well, technically not URLs, but URIs, or Uniform Resource Identifiers—that differentiate different types of data resources on a server.
A client can get data about a resource by making a request to that endpoint over HTTP. The request message has a very specific format. Most importantly, the start line contains the URI that you wish to access, which is preceded by an HTTP verb or request method, which signals your intent with the resource. A GET request means you just want to read the data, while POST means you want to create a new resource. PATCH is for updates, DELETE is for removing data, along with a few other methods.
Beyond those, below the start line, we have headers which contain metadata about the request. The Accept header can tell the server you want the data in a specific format, or the Authorization header can be used to tell the server that you're actually allowed to make that request. Then following the headers we have the body, which contains a custom payload of data.
The server will receive the request message, then execute some code, usually to read from a database, that can then be formatted into a response message. The top of the message contains a status code to tell the client what happened to their request. Codes at the 200 level mean that things went well. At the 400 level, it means something was wrong with your request, and at the 500 level, it means that the server failed. After the status code, we then have the response headers, which contain information about the server. That's followed by the response body, which contains the data payload and is usually formatted in JSON when talking about APIs.
Now, an important part of this architecture is that it's stateless, which means that the two parties don't need to store any information about each other, and every request-response cycle is independent from all other communication. And this leads to well-behaved web applications that are predictable and reliable.
Project Setup with Node.js & Express
This has been RESTful APIs in 100 seconds. If you enjoyed it, leave a comment below—then next week I'll pick out the best one to win this free t-shirt. And now it's time to go beyond 100 seconds to build a RESTful API from scratch.
The most popular framework for building RESTful APIs in Node is Express.js. It's been around forever, and it's very minimal and easy to learn if you know a little bit of JavaScript. Over the next few minutes, we'll use Express to build our own RESTful API from scratch. You'll learn how to create different endpoints for your API. We'll also look at slightly more advanced concepts like middleware and tools in the cloud for deploying your API, like API gateways.
To get started, you'll want to open up VS Code to an empty directory. You'll need to have Node.js installed, and I'm using version 12 for this video. To start a new Node project, let's run npm init -y from the command line.
Building the Basic Express Server
This will create a package.json and give us a context for installing packages that we can use in Node, like Express. Let's go ahead and install Express using npm install. You'll notice that adds Express to our dependencies in the package.json file. From there, we'll need a file to write our code in, so let's create an index.js file.
At the top of that file, we'll declare a variable for app, which represents the actual API that we're building, and its value is an import of the Express package, which itself is a function, so we'll add parentheses after it to initialize it. Now, at this point, our API hasn't defined any endpoints, but let's go ahead and run it anyway. The way you fire up your API on the server is by calling app.listen. That tells it to listen on a specific port, which we've defined as its own separate variable as 8080. Then as an optional second argument to listen, we can fire a callback to let us know when the API is ready, and we'll just have it console log the main URL.
We can now run the API by going to the terminal and running node . to run that index.js file, and it should console.log 'it's live on localhost:8080'. If we paste the URL into the browser, you can see we get a message of 'Cannot GET /'. That's because we don't have any API endpoints set up yet, but Express is still responding with an error message. In fact, you can open up the network tab in Chrome. If we look closely, we can see that our server responded with a 404 status code, meaning that page was not found.
Using a REST Client (Insomnia)
At this point, we know our API is working, but debugging it in the browser is usually not the best option. There are many different ways we can access our API. We could use cURL from the command line, we could install a VS Code extension, or we could use a REST client like Insomnia or Postman. I'm going to be using Insomnia throughout the rest of this video because it provides a really nice way to format your requests and also view a history of all your interactions.
From Insomnia, we can create a new request, then simply paste in our URL. We can easily change the HTTP verb from the dropdown menu here, click send, and then get the response in a nicely formatted, developer-friendly way. We can even see the timeline here with our request in yellow and the response in green.
Creating a GET Endpoint
But now we need to get back to our JavaScript and add an endpoint to the API. We can do that by chaining an HTTP verb to the app instance. If you type a period after app, you'll get IntelliSense on a bunch of different methods that live on this object, and you'll notice methods for get, post, patch, etc., which represent different HTTP verbs. If we want to add a GET endpoint to the /tshirt URI, we can do that by passing /tshirt as its first argument.
That'll automatically set up our server with that endpoint. Then it's our job to handle a request to it, which we do by passing a callback function as the second argument. Whenever a client or end user requests that URL, it will fire this callback function to handle the request. The function itself provides access to two different objects: the request object and the response object. The request is the incoming data, while the response is the data we want to send back to the client. The most important thing it does is allow us to send a response back to the client. That response can have a status code like 200 for an OK response. Then, we can send a data payload along with it. If we pass a JavaScript object as the argument, then it will send that data back as JSON by default.
Let's go ahead and save the file, then restart the server from the terminal. From Insomnia, we can then make a GET request to localhost:8080/tshirt. When we do that, we get a JSON object back as the response body with a status code of 200.
Creating a POST Endpoint
That's pretty cool, but now let's go back to our code and add a second endpoint. This time a POST endpoint, followed by a slash and a dynamic URL parameter that represents the ID of that t-shirt. There might be millions of different t-shirts on this API, and a dynamic URL allows us to handle all of them from a single function. When dealing with a POST request, it means that the user is trying to create new data on the server, or create a new t-shirt in this case.
First, we need the ID, which we can get from the URL, and its value is made available to us on the request parameters object. Second, we also need a logo for the t-shirt, but the logo is contained in the request body, which, if you remember from earlier, is a custom data payload contained in the incoming request. In other words, the request object in Express allows us to access information from the request message, like the URL parameters, the body, the headers, etc.
And now that we have that information, we could use it to save a new record to the database or something along those lines. That's beyond the scope of this video. What we'll do for right now is check to make sure that we have a logo in the request body, and if we don't, then we'll send an error response with a 418 status code and an error message that we need a logo. But assuming we do have a valid logo, we can just send a response with a t-shirt that contains that logo and ID.
Now let's go back to Insomnia, and we'll make a POST request to that t-shirt endpoint followed by a unique ID that can be whatever you want. Then in the body section, we'll go ahead and add a request body with a format of JSON, and it's just a JSON object that contains a logo with a string value. If we send that request, you'll notice we get a 500 error response, which means our API code is broken. So what's going on here? It's telling us we have a runtime error because we can't destructure the property 'logo' from the request body.
Using Middleware to Parse JSON
The reason for that is that Express does not parse JSON in the body by default. Not everybody uses Express to build a JSON API, so that's not the default behavior. What we need to do here is set up middleware that tells Express to parse JSON before the actual data hits the function that we're using here to handle the request. When you hear the term middleware, think of shared code that runs before every endpoint callback that you've defined.
Very common middleware is built into Express itself. We can refactor our code here a little bit to make a variable for Express, and then we can call app.use to apply middleware. In this case, the middleware we want to apply is the express.json middleware. Now, every request that comes in will first go through this express.json middleware, which will convert the body to JSON, therefore making it available in our POST callback.
Let's go ahead and save, restart our server, and then go back to Insomnia. And if we send the same exact request, you'll notice this time we get back a successful response. In addition, if we make the logo an empty string and try to send the same request, we get a 418 response along with a message that we need a logo.
Documenting with the OpenAPI Spec
Congratulations, you just built a RESTful API from scratch with Node.js and Express. But before we wrap up the video, there's one more thing you should definitely know about when it comes to RESTful APIs, and that is the OpenAPI spec, which provides a standard way to describe an API in YAML. It originally came about in something called the Swagger framework, and what it allows you to do is describe your API in a way that can be understood by both humans and machines.
And if you're building a serious API, you get all kinds of awesome benefits in the process. Your API will be fully documented, making it much easier for the end user to work with. And because it follows a standard format, you can actually just automatically generate all of your client-side or server-side code. What I'm using right now is a free tool called SwaggerHub, and I can come up here and hit the export button to automatically generate a bunch of boilerplate code. Now, I'm usually not a huge fan of code generators, but there's a more powerful reason to use OpenAPI.
When you describe your API with the OpenAPI spec, you can then upload the configuration to tools like API Gateway on AWS or Google Cloud, where it can be secured, monitored, and connected to backend infrastructure. Let me know if you want to see a full tutorial on that topic, but I'm going to go ahead and wrap things up there. And if you want access to even more advanced content, consider becoming a Pro member at fireship.io. Thanks for watching, and I will see you in the next one.
