Check out a free preview of the full API Design in Node.js, v4 course:
The "Anatomy of an API" Lesson is part of the full, API Design in Node.js, v4 course featured in this preview video. Here's what you'd learn in this lesson:

Scott explains the different components of an API including HTTP methods, route handlers, and how IP addresses and ports work. Most of the work of an API happens inside the route handler. These handlers can contain logic for determining how to handle requests, authentication, and limit the number of requests to protect the server.

Get Unlimited Access Now

Transcript from the "Anatomy of an API" Lesson

>> Awesome, okay, so we just did a lot on that HelloWorld API. And there's probably some things if you've never built an API before, they were like, what. I don't know how a lot of this stuff works. So, I was trying to be vague as much as I can, so I can actually get to this point on this page and not have to be moved.

[00:00:18] But, let's talk about a little bit. So, every API ever shares a common makeup. It really doesn't matter what the language or the environment is. So if you've ever built anything else with like Laravel or Django or Rails, it really doesn't matter. They all have the same little parts that that make them up.

[00:00:39] So I wanna talk about those parts. The first one is the server, okay, so we just made a server that had an API, okay. The API is the code that runs on the server, they're two different things. But people use them synonymously, when you hear people say API or people say server they're talking about the same thing, they're one in the same.

[00:00:59] But technically they're two different things. You can have a server that doesn't have an API. And I guess technically, you could have an API that doesn't have a server [LAUGH] now you can. But, they are definitely two different things. A server is basically an app that has no visual representation and is always running, right.

[00:01:19] So you might be using an app in the browser that has some type of UI but a server is also an app, it just doesn't have a visual thing the way you look at a service through the logs of a terminal. That's the server's visual output, right. It's usually connected to a network and shared amongst many different clients, so other UIs, web apps, mobile apps, other services, or the servers.

[00:01:43] Servers usually sit in front of a database and facilitates access to that database. That's the main use case I would say for most servers, it's literally a gatekeeper. It's like the people that sit, a bouncer at a club and the club the database basically, that's what a server is.

[00:02:02] And that bouncer has its own rules on what he wants to do and they never get off they just work there 24/7, they just never have time off. That's basically the server is. And basically in order to do that, there's some little networking things that are involved with servers.

[00:02:23] So, one thing is that servers must operate on a port. So if I go back to the code that we just wrote, this number here, that's a port. This is a port on your computer. And you can think of a port almost like a port in a ship dock, it's kinda the same.

[00:02:39] It basically, is just like some number, typically four digits, sometimes five digits. But it's like a virtual place on your computer's operating system, where network connections start and end. So, you cannot interface with anything on a network without it being attached to a port. Just like you can't interface with your boat unless you pull into a port, no one's gonna come unload stuff unless you pull into the port, that's the way that you connect to the network.

[00:03:08] So you need a port and it has to be unique. You can't have more than one thing on the same port. In fact, you'll get an error if you try to do that. If I tried to start another server right now, on 3001 while another one's running, it will say no, that ports being used right now someone's already parked there.

[00:03:24] So you can't, pick another number, okay. And then you have something like an IP address. So an IP address is that unique location of where the server is located on the network. You can think of it as the address to your home. It's unique, that's how the Mill and UPS and FedEx that's how they find you because you have a unique address.

[00:03:44] If your address wasn't unique, and someone else had the same address as you, how do they know which one to deliver it to? That will be weird, right. So an IP address is unique on the network that it's on and the internet is the biggest network in the world.

[00:03:57] So, every IP address on the internet has to be unique. On locally right now, it only has to be unique for your computer so it's less sensitive there. But basically an IP address just helps traffic go to and from a specific device whereas a port allows targeting of specific services or apps on that device.

[00:04:20] So, if I wanna locate a computer, like, this would be an alias for their IP address. This will take me to their server. And what you don't know is that there actually is a port here called 80, is that most browsers just take that away cuz it's always 80, but it's there.

[00:04:40] And 80 is the port on Google server that's gonna show me the HTML page that shows me the Google search box. That's what they decided to put there. So when I go there, I'm connecting to that service. But locally, they might have other ports that have other services that they use, whether we have access to them or not.

[00:04:57] So yeah, that's ports, that's IP addresses and it looks like this. So, you can see here this will be an IP address. This is actually the IP address for a localhost, which is the server running on your computer right now. Everyone has a server on their computers called localhost and that's the Alias.

[00:05:15] But the official IP address forward is this and then everything after the code is the port.
>> Just wanted to confirm, I think localhost is usually 127.
>> Is it 127, what did I put?
>> You got 121.
>> Yeah, it is 127, you're right, damn. All right, and then, a route.

[00:05:30] Let's talk about routes. So, a route is a unique combination of a URL path and an HTTP method. So routes are used to locate certain resources or trigger certain actions on an API. And basically, you can think of them as, if you're on the front end and click is the name of an event, a route is the name of the event.

[00:05:50] And it's a combination of the path you wanna go to plus the HTTP method that you're trying to do, okay. So, an examples of methods are the least the most common ones that are built into HTTP are GET, so we did GET that's the one that we check for in our server, we check for a get request.

[00:06:09] Typically it's used to show intent of, I wanna get information from API. Then there's POST, POST is typically used to mutate or create information on API. Usually there's some data being sent along with it. Then there's PUT, PUT is usually used to be for replacing existing information on API.

[00:06:28] It also has data typically sent along with it. PATCH is like PUT but it doesn't replace it, it just updates it. So, it doesn't actually swap something out. It just changes something a little but it also usually has data sent along with it. And then DELETE is exactly what it sounds like.

[00:06:44] It's typically used for deleting things off of an API, some information. And then you have this other one called OPTIONS. This one is used by something called CORS, we'll talk about CORS, but it's basically browsers are like super sketchy about allowing you to talk to other APIs. So they implemented this security check to make sure you have permission to talk to the API.

[00:07:03] That security check is called CORS and the way they do that is by sending up some HB medical options basically it's like, hey Mr. API, what are your options for this client trying to talk to you? And that's what that is. So, those are the most common HTTP methods.

[00:07:22] There's more, but I doubt you'll ever use them. You're probably only ever use these and you probably won't even use OPTIONS. You're probably only ever use, GraphQL you're only ever to use this or this. You wanna use anything else. It depends on what you're doing. But for the most part, this is what HTTP is made of.

[00:07:43] And here's an example what a route will look like. So a route, I said, it's a combination of a method and a path. So in this case, this is a GET request to whatever your URL is/api/user/1. Another example would be POST to whatever your URL is/ food. And that is the unique combination that triggers an event.

[00:08:08] So really an API is about registering all of these unique URL combinations and then creating functions that respond to them. It's literally an event based application. And the tough part about this is that, engineers just do whatever they want. Even though we talked about these methods in these routes.

[00:08:35] Yeah, that's true for pretty much every single server and server technology. But that doesn't mean engineers wanna do it, some people just don't even respect they gets to the POST. They might treat a POST like a GET, they might treat a DELETE like a POST. There's nothing stopping you from doing it.

[00:08:52] You can do whatever you want. It's your code, that's why we have come up with different design patterns for API. So we can all agree that hey, if you adopt this design pattern, I should expect your API to work a certain way. And the most popular one is called REST.

[00:09:09] And we're gonna be talking about REST here. There's others like gRPC, GraphQL, and Protobuf, that do different things, but we'll be talking about REST in this one. And how loose it is because it is very loose. I don't think anyone does REST the way that you're supposed to do it.

[00:09:27] I don't think he can. I don't think it's possible, in my opinion. But, we're gonna try it. Last one here is route handlers. So, what is a route handler? A route handler is this, this callback right here. That's a route handler. It's just a function that responds to an event just like a handler for a click event or a hover event.

[00:09:46] That's basically what it is. Typically what you do in a route handlers, this is where you would talk to the database. This is where all the magic happens. This is the thing you're trying to protect is the route handler. So, that's why you have a server in the first place.

[00:09:59] Cause if you think about how a client works, when we all go to the same website, we all get our own version of that website. But, when each version of that website talks to the server, we're all talking to the same server. There's only one server for all of the copies of the website that we're looking at.

[00:10:18] So the server needs to be able to respond to all of us and that's how it does it by having a route handler responding to each and one of our individual requests. And I think that's the different approach coming from front end is that you gotta realize you're not building an app for one user, you're building an app for every user.

[00:10:36] Every user ever is gonna use this at the same time. And it has to respond to that and it's a different concern.