What Is REST?

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

00:08 REST stands for Representational State Transfer. I promise that’s probably the only time you will hear that. It comes out of a PhD dissertation by Roy Fielding from just over 20 years ago. Dr.

00:22 Fielding defined the REST protocol based on the HTTP standard at the time, making it something that could be implemented without making changes to the network. Anyone who could run a web server could run the REST protocol.

00:35 Not surprisingly for a PhD dissertation, it reads a bit like a PhD dissertation. It contains six architectural constraints that define the protocol. The first is client-server architecture.

00:49 This is the idea that there’s a separation between the UI and the data storage and processing. As HTTP is already client-server, this fits nicely.

00:58 The second constraint is statelessness. No client context is stored on the server between calls. The client has the only context. Any call should be repeatable on the server.

01:10 HTTP is already this way. In fact, cookies were created inside of the HTTP protocol to get around this fact. The third constraint is cacheability. The protocol needs to be able to support caching on the client side. Once again, this maps very nicely to web servers.

01:28 Web servers already introduce cache headers to indicate whether or not data has changed on the server side. The system must be layered. This means that things like proxies and load balancers could be between the client and the server and should not affect the client or the calls.

01:45 The fifth constraint is the ability to have code on demand. I’ve never actually seen this one used with REST, but it is possible. This is similar to the idea of having HTML and JavaScript come down with a webpage—both data, UI, and code, in that case.

02:03 The sixth constraint, a uniform interface, breaks down into four properties. The first is: Resources are identified as requests. Essentially, URLs are what specify the data.

02:15 The uniqueness of the URL specifies the uniqueness of an item of data. Secondly, resource manipulation through representation. Data itself has enough info to modify or delete the data.

02:27 The data is self-contained. This is usually implemented through the use of URLs, so the data corresponds to a URL and you can use that URL to do things like change the data or delete the data on the server side. The data is intended to be self descriptive.

02:44 If there’s information that is needed about the encoding of the message, it is included in the message. This is similar to the accepted types header inside of HTTP, which indicates what kind of encoding the client supports. And finally, the rather dubious acronym, HATEOAS—Hypermedia As The Engine Of Application State.

03:04 This means links are how you do things. Data should contain links that specify how to manipulate that data. This aspect is one of those that’s often ignored.

03:14 I’ve seen plenty of REST-like protocols that only use ID numbers inside of the data rather than full URLs. But there is an advantage to embedding the URL.

03:23 It makes it very simple to go back to the server and get more information simply by using the associated URL. In the overview, I mentioned that REST is the protocol that isn’t quite a standard.

03:36 “The code is more what you’d call ‘guidelines’ than actual rules.” I really probably should have done that in my best pirate voice, “Ar.” In practice, what this means is every implementation is a little bit different.

03:50 Oftentimes, only a subset of REST is implemented. When I first started writing REST interfaces, I very seldom implemented the entire protocol. Frequently, I was just doing XML over HTTP, using GET to get the data, which is REST-like, but not bothering with all the puts and patches and other things. For example, using POST to make changes, which isn’t quite REST-compliant.

04:16 This lack of adherence to a standard sounds like it might be a problem. How are you going to know what to do? Because the protocol is based on top of HTTP, you don’t need any fancy libraries in order to access it.

04:28 Any library that supports HTTP supports the use of REST. As a result, client-specific code ends up being just that—client-specific code. So whether or not the implementer used POST correctly isn’t going to matter very much because you’re going to have to look up the API’s documentation as to how to talk to it anyways.

04:47 This allows a rather lazy approach to your coding, in the fact that the clients only have to implement the minimum necessary to access your API, and nothing more.

04:57 The good news about this is it makes REST far more lightweight than similar technologies that are all-encompassing, like SOAP. The bad news about this is sometimes you have to pay a little more attention to the documentation to know how you’re going to use it.

05:12 You can get away with this being so ill-defined because REST is built on top of well-known standards like HTTP. If you’ve done any web programming, you’re probably already familiar with the idea of HTTP GET and POST. REST uses these as well as other HTTP methods.

05:29 Let me run through the different kinds. As I mentioned, GET, the most common one. This is what happens when your browser goes and fetches a webpage—it’s getting the webpage over HTTP.

05:40 The GET method inside of REST is used to either get a single resource with a fully qualified URL—usually including an identifier—or to get a listing of resources.

05:52 POST is used to create a resource. In the web world, POST is used for submitting forms. The body of the POST contains the fields of the form. In the REST world, the POST is used to create a new object.

06:07 Those same fields are used to specify the fields of the object that’s being created. The URL that you’re posting to specifies what object is being created. PUT is somewhat like POST. It uses the fields to specify information about the object, but in this case it’s to update the object. PATCH also is used to update the object.

06:30 The difference between PUT and PATCH is that PUT requires you to specify all of the fields and replaces them in the object.

06:38 PATCH allows you to specify only a subset of fields and only changes those fields that are given.

06:45 And finally, DELETE, obviously enough, deletes the object on the server side.

06:51 Let me run you through some examples. Here’s a URL that if you call the GET method on will retrieve a list of books. Further refining the URL to specify an ID and doing a GET will not get all of the books, but a specific book—in this case, the book with id=12.

07:08 Posting to the books/ URL will create a new book. The body of the POST contains fields title and author to specify the title and author of the book that is created.

07:19 Typically, the REST protocol will return the object that was created, with its ID information.

07:26 POST goes just to books/. PUT goes to a specific book—in this case, book number 23, the book that was created in my last example.

07:36 Similar to POST, you specify fields—the title and the author. In this example, the title is the same as that which was created in the previous one, but the author has been changed. Because it’s a PUT, I have to specify all of the fields.

07:52 Here’s a PATCH on the same thing. PUT requires all of the fields. PATCH only requires the fields that I’m changing. So again, I’m specifying book 23, but this time only specifying the title.

08:04 The author will stay Franz Kafka and the title will change from Metamorphosis to The Metamorphosis. And finally, here’s a DELETE. Similar to a GET, it specifies a URL that fully qualifies the book. In this case, I’m deleting book number 12.

08:22 The REST protocol does not specify the format of the payload. The most common payloads are JSON and XML. The DRF, which the rest of this course is about, supports these out of the box, and there are third-party packages that you can use to add onto the DRF to support other ones as well. A popular one adds YAML as a payload.

08:44 Let me show you an example of what a JSON payload looks like. Here, I’m using the curl command to fetch a list of books. The -s parameter specifies silence.

08:55 This stops curl from showing the progress information. The URL that I’m hitting is the localhost on port 8000—for example, on my own little Django server—and the path I’m hitting in the URL is books/, because I want a list of books.

09:10 Normally what comes back from the server is an undifferentiated JSON blob. That tends to be hard to read because it’s all in the same line, so I’m going to augment this command with a pretty printer.

09:21 There are a whole bunch of different programs you can use to pretty print JSON, but seeing this is a Python course, I’m pretty sure you’ve got Python installed.

09:30 You can use Python’s json module directly to pretty print. Calling python -m here specifies to run the json.tool module.

09:40 The json.tool module will take whatever’s passed in on stdin (standard in)—in this case, from the pipe (|)—will pretty print it, and put it to stdout (standard out)—the screen.

09:49 So I run the command and I get the following result. Here’s some pretty-printed JSON, which includes a dictionary. The dictionary has one attribute, which is "books".

09:59 The "books" attribute is an array that contains two books, "The Metamorphosis" and "The Stranger".

10:06 Obviously, I was in a bit of an existential mood when I wrote this.

10:11 That’s the basics of REST. Next up, I’ll dive into what you’re actually here for: the Django REST Framework.