Intro to REST APIs

00:00 In the previous lesson, I gave an overview of the course. In this lesson, I’ll introduce you to REST.

00:07 REST is short for representational state transfer, and it is kind a standard, more like a suggestion. It was originally defined by Roy Fielding in his PhD dissertation.

00:19 Since it was a PhD dissertation, it goes into all sorts of details, but it truly boils down to using HTTP protocols for communication and some sort of serialization for payloads. In most cases, only a subset of calls is implemented.

00:37 I often end up with interfaces that only ever use GETs and POSTs, not bothering with anything else. A lot of that depends on who is consuming your interface.

00:47 If you’re building a generic API for others to use, you want something more robust. If you’re just building the back end that your front-end devs are using, you build what you need and skip everything else.

00:59 This means that documentation of your API becomes rather important because someone writing against it can’t really assume what is there. The end result tends to be rather minimalist, which is actually a good thing, as what you build and what you need typically is much lighter-weight than competing protocols like SOAP.

01:19 There are five main HTP operations that are usually used in a REST interface. GET, which is what your browser is doing when you view a web page, is used for getting an object or a list of objects.

01:33 POST, which is what your browser is doing when you submit a form, is for creating an object on the server. The request body contains the fields needed for creating the new thing, and the response usually contains the newly created thing.

01:49 POST can also be used to update an object, but using PUT instead makes it clearer when you’re doing a create vs when you’re doing an update. Like with POST, the body for PUT contains the data for the new state of the object.

02:05 PATCH is another way of doing an update. PUT supposed to send all the fields for the object, whereas PATCH only sends those fields that change. Again, nothing enforces this, but stick with the convention, or you’ll confuse your API users.

02:21 Finally, DELETE, somewhat predictably, is for deleting a a given object from the server. This usually takes just the ID of the thing to be removed.

02:32 Let’s define an interface for a library—I mean room with books in it, rather than the programming kind. First off, I want to get a list of available books. The URL indicates what kind of resource I’m trying to fetch. The API may also have an authors list, a publishers list, and more. The response to this call would contain a serialized list of books. Depending on the API, it might contain just some IDs, but more likely it’ll contain enough data that the list of books can be presented to the user.

03:03 So, title, author info, any of that kind of stuff would be embedded.

03:11 If I have a book’s ID and I want info on just that book,

03:14 I use a different URL. A common pattern is to append the ID to the same base URL as the listing. Calling this URL without an ID gives the list. Calling it with the ID on the end gives a single result. This maps nicely to how Django uses arguments in URL paths. Great, so I can look up a book. Now how do I create one?

03:39 The HTTP POST operation is used for creation. It also uses the same base URL. The different HTTP method is what indicates that I’m doing something different, a create instead of a fetch. The body of the request will include some set of name-value pairs with the needed data for creating a book entry on the server.

03:59 Here, I’m passing the title and the author. It’s common practice for this call to respond with the newly created object, using the same format as what you would get if you called GET with an ID.

04:14 If I want to update that book, I use the same base URL, a specific ID, and then call the HTTP PUT operation. Like with POST, I send the book’s attributes in the request body.

04:28 The only difference here is that instead of creating a new book, book number 23 will have its fields set to the given values. By convention, a PUT call should include all the writeable fields for the book—all the same fields used in the POST.

04:44 PATCH is very similar, but you only need to send what has changed. In this case, I’m updating the title. All other fields will get left alone. Being a lazy developer, I often only implement the PUT and not bother with the PATCH.

04:58 Part of that has to do with the front-end libraries I’m using, which usually just send everything that’s in the object. That being said, the PATCH is more flexible. You can always send all of the fields.

05:10 Finally, if I no longer want the book in the database, I use HTTP DELETE. Once again, same base URL, and once again, giving the ID of the object to be manipulated.

05:23 REST is intentionally vague about the data. It doesn’t care. On one hand, that means you can’t make any assumptions about an unfamiliar interface. On the other, it gives a lot of flexibility.

05:36 Although you could build your API to use any sort of serialization, JSON and XML are the most common. And even then, XML is starting to fade a bit. I’m typically only seeing JSON around. Of course, there are variations on JSON and multiple kinds of JSON. So, you know, it still keeps things interesting. Here’s an example. If I want to use the curl command to fetch a list of books, I would give the URL to curl, and it would spit back JSON.

06:05 Now, as JSON without newlines and tabs can be a bit hard to read, I often pipe this through a Python programs that pretty prints the JSON. The program is built into the standard library, and you can call with the -m command-line switch. And there’s the result.

06:22 The -s argument to curl tells it to be silent. For larger payloads, curl will show a progress bar. As I am uninterested in that info, I use -s to turn it off. Once curl hits the server, it prints out the resulting JSON. I used Python to make it easier to read, and all of that ends up in the terminal. To make parsing easier, most REST APIs that use JSON always send back the same thing—an object.

06:52 My example here is an object with a list inside of it named books, and each book itself is represented by yet another object. For Python programmers, this makes a quick call to JSON’s .loads(), and you’re in dictionary land, which is a happy place to be.

07:12 Okay, you’ve the protocol basics down pat. Next up, I’ll show you how the Ninja library helps you write all this stuff.