API Design in Node.js (using Express & Mongo) Anatomy of a REST API
This course has been updated! We now recommend you take the API Design in Node.js, v4 course.
Transcript from the "Anatomy of a REST API" Lesson
>> Speaker 1: What we're gonna do is, we're gonna create an API to consume some data about lions. Just Internet cats. So first we should determine what the actual resource looks like and we can model this in JSON. When I say resource, I mean what does the actual lion look like, cuz we're gonna be making this thing that consumes lions.
[00:00:22] What does a lion object look like? We need to model that first. I'm just gonna show you what that looks like in JSON. This is what our data's gonna look like. So it's gonna be an object that has a name property, ana ID property, a pride property where the lion pride belongs to, and then a gender property.
[00:00:39] So, that's what a lion looks like. So this is us modeling our resource or our data. So it's like the first step. Cuz everything is built around how your data is modeled, so it's always good to start off modeling your data first because if you do that last, [LAUGH] you're gonna run into some problems.
[00:00:56] So definitely model your data first and know what your application's gonna be working with, what it's gonna be consuming, and that's gonna help you out and it's gonna allow you to build mock things out. Without having to wait on on the backend to build up. Because if you are a front end developer and I gave you this JSON object and was like, here, this is what the data's gonna look like.
[00:01:14] You can like, okay, I don't have to wait on you anymore. I can just go mock this stuff out. Right, cuz I know what the data looks like. Whereas if the back end person didn't give you this first and was like, I'm not doing the data until the end, then how do you, as a front engineer, know what to do, what the data's gonna look like?
[00:01:28] So it's really great to start with this and it helps you out with the rest of the application. This is a basic example of modeling your data. When you get into databases and stuff, of course, it will be more difficult than this and a little more work you got to put in.
[00:01:39] A little more thought as far as relations between models and stuff like that, but, on the simplest level, this is all it is. This is just representing a adjacent object of our lion. Any questions on that? All right, so when you hear me say the term resource, this is what I'm talking about.
[00:01:56] So, protect your resources, how do we access our resources. The resources is the data. These are the resources, the actual data. So, next we should design the routes to access the resource. So following REST, we want to use the HTTP verbs. So the main ones we're gonna be using are gonna be get, post, put, and delete.
[00:02:20] Who is here not familiar with those HTTP verbs? Okay. So get request means I'm trying to ask for something. Post means I'm going to give you something. Put means I'm going to update something. And delete means I'm gonna delete something. So, we've come up with a term for that, and that's called CRUD.
[00:02:47] Create, read, update, delete, or I guess destroy, not delete, that should be destroy, but same thing. So we will be performing CRUD operations on the resource. So you'll hear that a lot if you've never heard that before. I'm gonna be using it a lot, you'll hear that a lot, when you develop APIs and stuff.
[00:03:02] You wanna perform CRUD on some types of resource. Create, read, update, destroy or delete. Cuz that's really what applications are about, is doing that. So again we're gonna diagram how that looks like, as far as the routes, and what we expect when we do certain verbs on certain routes, and what we should get back.
[00:03:21] So we're gonna diagram that with JSON as well. So here is a JSON diagram of that. So how we read is if I do a get request to /lions, I expect it to return all the lions and the response should be a 200 and its type should be application json and it should be an array of objects.
>> Speaker 1: So going back to REST, this is like the URL structure that I was talking about. Just by the URL, I know exactly what resource I'm gonna get because it's called lions. So I know that this is the lions resource because of the naming here. It's not that deep, so it's not that good of an example, but because of REST, I say /lions, I know I'm getting the lions resource.
[00:04:10] And because I do a get request to lions, I should get back all the lions, and it should be an array of every lion and it should be json. So the next one is /lion/id, so here's the URL a little deeper. So all lions have an id. So here's that directory-like structure.
[00:04:29] So, if we think about it as lions, as an object, all right, they have an id property on it, so /lions/id. That's the URL structure that I was talking about. So if I do a get request to /lions/ some number, it should return one lion represented by that id.
[00:04:47] It should be response of 200 application json and it should just be an object of that one line. Is everybody following here? Yeah.
>> Speaker 2: I have a question. Are we actually defining routes and return values or are you just laying it out?
>> Speaker 1: I'm just laying it out.
[00:05:04] This is a blueprint. Yeah, we're not doing anything right now. This is just a blueprint. Yeah, all right, cool, yeah. I just chose JSON because we all know JSON. Most people define their API blueprints in something called YMAL or some other thing like that. So, or even markdown, but I'm just doing it in JSON cuz we all know JSON.
[00:05:26] But yeah, we are not defining anything. You will be defining something. And this is the blueprint that you're gonna use to define those things in a minute. But we are not defining it right now. I just wanna walk through this blueprint to help you understand how I came up with this stuff.
[00:05:38] It just wasn't off the top of my head, this is RESTful stuff right here. And then if we do a post request a lion, that should create and return a new lion using a posted object as the lion. So post means I'm gonna give the resource some object, and I'm expecting the resource to create something with that object and then I expect after the creation, I expect the object to be returned back to me.
[00:06:05] If you think about it, that makes sense, because think about if you're making a to do app and you type something in, you hit Enter and you made a new todo. And it went to the server and it created it but the server never responded back with a new todo.
[00:06:19] How would you update your UI? So you need a server to come in like, okay, here's the thing that will just create it when its ID cuz most of the time the database creates the ID for you, and you need that in your UI for whatever reason. So the server should respond back with the thing that it just created, after it created it, or an error if it couldn't.
[00:06:39] So the response for that should be a 201 successful post, that's their HTTP status code for that. 200 works as well but 201 is the actual status code for a successful creation. application/json and it should just send back that one lion that it made. I don't need an ID here because I'm not referencing something, I'm creating something, so I'm gonna send you an object, just create the lion for me.
[00:07:06] But I do need a ID here because I'm referencing something, I'm trying to update something that exists on the server. So put, just like with the GET1 up here, it's gonna take an ID and it's going to update and return the matching lion, with the posted update object.
[00:07:23] So what that means is you do a put request with the server, with the ID, and then an object of the things that you want to update the lion. For instance, let's say you want to update the name and the age, so you'll post an object with a new name and a newage.
[00:07:38] And the, what I'm expecting to happen is for you to find that lion whose ID matches the one that I asked you and to update those values of the object that I posted and then return the newly updated object to me as Json. And, it should be just one object, it shouldn't be an array.
>> Speaker 1: Everybody following me on this so far? So this is just the blueprint. This is REST. This is, believe it or not, almost all the services you use now are just like this. If you ever consumed any API, it was probably like this, something close to it. Some people get kind of crazy with their APIs but something like this.
[00:08:21] A good API that I can off the top of my head think of that follows this pretty good is Parse. If you ever used Parse before, they follow API, REST, to the t, they're really good at that.
>> Speaker 1: And then the last one is delete. So if we do delete request, two slash lines ID, same thing, we need a ID here cuz we're referencing an ID on the server.
[00:08:42] So we need to find it, and what I expect to happen is for you to delete it from the collection of resources, and return the thing that you just deleted with a response of 200 and then just that one object. So that's the blueprint of all these specific CRUD actions we can do on one resource, yes.
>> Speaker 2: Any opinion or use of patch versus put?
>> Speaker 1: I don't, I don't have an opinion, I don't know the differences well enough to have a really good opinion on the two things, but yeah, I don't really have an opinion on that, I usually just use put.
>> Speaker 1: Okay, so now that we have our resources and our routes modded out, we can actually start building this API with Express.
[00:09:28] So we're gonna use this as our blueprint and we're actually gonna build out these routes that serve these resources. And there's gonna be a little website on the frontend that is gonna consume this so it's gonna be expecting this. And then for extra credit, if you really know REST and you really want to get really good with it, you can allow query params on the get request to allow filtering and ordering of the lions.
[00:09:51] So what that means, when I say query params, I mean if I were to come in here and was like, on the URL and I was like, yeah, sorts by name or something like that. And then you could do stuff like that, so that's also part of REST.
[00:10:11] So if you know how to do that, totally do that, but you don't have to.