A discussion of Django REST Framework, how it integrates with traditional Django, and its core features.
Carlton Gibson 0:08
Hi, and welcome to another episode of Django chats. I'm calling Gibson. I'm here with Will Vincent. Hi. Today we're going to talk about Django rest framework, one of the main third party add ons in the Django ecosystem, the main one that you use for building API's with Django.
Will Vincent 0:22
Yeah. And I would, as we've discussed previously, I would say the number one third party application you're likely to use. So as you mentioned, it's it's how one builds API's. So we're going to talk about why would you why you would do that and get into the specifics of Django rest framework to keep it simple, right. We've introduced this term API, what what's an API? So an API stands for application programming interface, which isn't that helpful. But it's, I think of it is the way in which two computers talk to one another. And the key difference between a, you know a website a traditional website has all sorts of things. It has HTML, CSS, Java, Have a script, all working together within Django to give you a web page, an API is just the data. So you often have to combine that data with those other HTML CSS attributes. But why don't you give it a shot? I don't think that's the clearest explanation.
Carlton Gibson 1:17
Will Vincent 2:13
Right? Yeah. And I think that, you know, to repeat what you've said, if you want to work with a front end framework, so something like react or view or Angular, you will need to, you'll be better served to use an API internally. But you can also use an API to talk to multiple clients. So the example I like to give is with Instagram. Instagram is one database that has an iOS app, an Android app and a web app. So how do three clients talk to one database with traditional Django you can't do that. It's more all in one box. But if you create an API, and in that case, it'd be an internal API. So an API only that Instagram programmers or applications can use. They can all speak to one another. You can have multiple clients, multiple front end interfaces with one code base. And this is really the direction that most websites are going these days. You can start with just traditional Django. But as soon as you want mobile, or as soon as you want to add these front end frameworks to your own application, you're probably going to switch to an API.
Carlton Gibson 3:20
Yeah, that sounds about right. So if you want to build an API with Django, what are you going to use? You're going to use Django rest framework.
Will Vincent 3:27
So now you're going to use Django rest framework. Yes.
Carlton Gibson 3:29
Right. So what's the rest of that? What's the rest of that? We know what Django is. And we know what a framework is. Django is a framework. It's a framework toolkit, but what's the rest of it?
Will Vincent 3:38
Right, so rest, here's another acronym represent representational state transfer, which I don't just like Application Programming Interface, I don't think Is that helpful. It is an architecture style. Only from the year 2000. Roy fielding did his dissertation. It's basically a set of rules or suggestions for how to structure an API so there's some Cotonou to it, there's and really what it does is it makes you learn HTTP, hypertext transfer protocol.
Carlton Gibson 4:07
He says that the being of URLs, right?
Will Vincent 4:09
Carlton Gibson 5:40
verbs here, like these chords. This is the key point for me is like, all the other stuff is stateless. And whether it's kind of interesting, but the key point for me is that the HTTP that each how many T's was that the HTTP verbs correspond to the methods of crud base as normally understood, so you get to read Riva a resource, you can post or put to create or update, you can delete these HTTP verbs, say how you use it. So each resource will have a URL unique for that resource. And then the action that you perform will depend on which HTTP verb you use.
Will Vincent 6:19
Yeah, and I, you know, I'd like to do a separate episode just on crud because I feel like crud, which stands for create, read, update, delete is something that web developers internalize quickly and understand. But if you ask an average person, or you explain to them that every site basically just has crud with authentication, you'll you'll kind of blow their mind, I think, because if you really, you can say to them, let's look at twitter. Let's look at Facebook. Let's look at Instagram, Pinterest, Google. It's the same thing over and over again. That's a real aha moment for people. And so if you once you start building API's, you will get that even with traditional Django a lot of that is handled for you. So you might Not necessarily know about HTTP, you might not know about these verbs. It's really when you build an API that it will become real to you.
Carlton Gibson 7:08
Okay, fine. You know, that's very abstract. But what does Django rest framework give us? DRF? What does DRF give us?
Will Vincent 7:16
Right? So right, so Django Django rest framework. So Django, you build the websites and you say, right, I want an API, Django rest framework, third party package, so you can easily install it. And because it intentionally mimics Django conventions, it will transform a traditional site into an API for you with a tiny amount of code, largely through something called a serializer, which I think of is really the magic which will transform instead of sending a webpage back and forth, it will send just data typically in the form of JSON. So I think serializers is the number one thing that's along with HTTP that differentiates an API from a website and that people need to understand what a serializer is and how it does what it does. Because Django rest framework really just kind of magically transforms your site into an API, but it's doing that largely through the serializer.
Carlton Gibson 8:07
Yeah. And the generic views as well. So if you want to create a view, which just retrieves an object, there's a retrieve API view. And if you want to create an object, there's a create API view. And if you want to update an object, there's an update API view. And then there's generic views which create retrieve API view like that. Combine these.
Will Vincent 8:30
Yeah, very similar, you know, intentionally similar to changose. Generic class based views, which is why I recommend people start with Django and then Django rest framework, in the same way that building an API, you shouldn't build a website first. Because, you know, Django rest framework, you'll appreciate it more, it'll make more sense. You'll see that's built upon Django itself. So I definitely recommend building a couple. If someone says to you, your boss says to you go build an API with Django rest framework, build a build a site or two In Django first, and then you will see that you can quickly add on an API. But it will make a lot more sense within the context of, you know, this is all meant to be very Django, like in terms of its structure.
Carlton Gibson 9:11
Yeah. And I think that's the basic structure of DRF is you take the model, which you've which you've got in you're very familiar with, from your building your normal Django sites, you've got a model, and then you create a model serializer. And it's basic, all you have to do is declare which model it uses, and it will automatically create all the right fields for you. And then on top of that, you just put a view in place, and then the framework better Django rest framework. It does all the rest, it handles encoding the model data into JSON for you, it handles passing incoming JSON data if you have a post view. So it's just super for that reason.
Will Vincent 9:48
Yeah. And you start the URLs, right, so that so you have your model, you have your URLs, and then you have views for a traditional Django site. We also would have templates. There's no templates with Django rest framework. Because we're dealing just with data, the difference is instead of templates, you have serializers. And the views are a little bit different. But the models are basically the same. And your URLs are the same that relies on Django itself. So it's really the serializers. And the views, which are different.
Carlton Gibson 10:16
Yeah, I mean, then under the hood, there's these things called renders, but the users, normally you would just never get that you tell it that you want to support JSON, and it would use a JSON renderer. And unless you're getting right into the advanced stuff, you never need to see that layer. That's what's super.
Will Vincent 10:31
Yeah. So just just like Django, you really you can get it and use it. And then if you need to go deep, you can be don't have to right off the bat. We should mention, I mean, you are a core maintainer of Django rest framework. So you know, that if which you speak, well, it's actually worse than I do.
Carlton Gibson 10:47
Yeah. Well, I go into it a long time, long time ago. So I was building iOS apps for in a freelance environment and agent environment and clients needed not only an app, they needed an API to go, they need something for the for the mobile application to talk to. And I knew Jango. Once I was like, Well, I can build the back end. And looking for something at all, which enabled me to build API's with Django and Django rest framework popped up. This was version one days. And then I was following it along and using it, and Tom Christie, who was the creator of Django rest framework, he came on the mailing list one day, and he's like, Look, I need help. This is there's too many issues to triage is too many questions on Stack Overflow, the mailing list is too hard. So I got onto the mailing list. I got into Stack Overflow, and he started answering questions and helping out and all of a sudden, turns out oh, you know, you're here. You can be a maintainer on the framework, and I'm closing tickets and merging pull requests. And so you know, and that was that was how I got started in open source was, I was using gangers. I was using Django and Django rest framework. And Tom needed help and I just, I just chipped in, you know, I just did my bit.
Will Vincent 11:56
Yeah. Yeah. Well, and it's interesting because you That you got it, you know, because you're currently a Django fellow as well. But you got into the Django world through Django rest framework. Yeah, you've already
Carlton Gibson 12:07
done it. And you know, I needed I needed to build API's and Django rest framework was an is just a super way of doing that.
Will Vincent 12:15
Carlton Gibson 14:39
Yeah, so how do I know that this HTTP request which has nothing to do with the previous one is from the same person was because they have the same token or the same identifying feature? It could be a cookie, it could be a token as you say it of some kind. And and that's the key right? It is HTTP, the underlying protocol is stateless. So it has no concept of the session. So we have to just because you log in on the login page, and then you're taken to the homepage, the site doesn't know that you then can reload it, for example, is exactly the same with with a, you know, traditional Django application, you have to have that cookie, you have to log in, and then the the back end sets the cookie for the next request to know it's you. What I would say that if you're using an API to augment your website to look like you're doing it in that example, that I gave at the beginning of enhancing a form submission with Ajax or anything, where they're in the browser, just use session off the same as the default session off the same cookie authentication that you always have in the browser. And then if you need some other client to come along, that's when you need to go to one of the token methods, be it JW T or OAuth tokens, it's
Will Vincent 15:52
unkind and be aware that it is it can be very complex.
Carlton Gibson 15:57
Yeah, and they will
Will Vincent 16:00
Carlton Gibson 16:21
Yeah, I think that's the key point is it is complex. And when you get into authentication for multiple clients, you just have to be prepared to spend the time to do it properly and to understand what's going on and to dot the i's and cross the T's.
Will Vincent 16:34
Yeah, and you don't want to get authentication wrong. Well. Yeah. So what else another key point when you're learning about API's and rest Django rest framework is the concept of course, co Rs, cross origin resource sharing, which is a fundamental security feature of the web, it basically means that you can't, by default, make cross domain requests. So if I'm on you know, site a.com It won't, by default, let things come from site b.com. Because that would be a way for a hacker to basically take over your website. So you have to explicitly give permission, which you do through cores. So when you're setting up your API that can often live on a different server than your front end. So you need to specifically say, this front end can access my back end API. If you don't set that. It won't work. It's a small thing. But it's something people may not have thought about if they're just coming from a web framework world where that's sort of handled for them.
Carlton Gibson 17:35
Yeah. And there's a third party package to help desk.
Will Vincent 17:38
Yes, yes. Yeah, supertanker, of course is which will link to
Carlton Gibson 17:42
take my Johnson who's ever, you know, contributor and
Will Vincent 17:46
yeah, you have to use that with Django rest framework.
Carlton Gibson 17:49
Yeah. So like this, the companies, right, you've got app.my product calm, and then you've got api.my product, the common app, the app.com, wants to talk to the API. I can't do that without setting the right
Will Vincent 18:01
runkles right. And again, this is understanding HTTP, where headers is this. It's almost like the metadata on a normal page where, you know, you go into view source and you see meta, you know, the title is in there, and the author and maybe some other stuff, it's sort of secret, secret information that's really important. I would say, documentation what to say about this, Carlton, because, you know, in an API, you need to have a roadmap to understand it, so someone can understand how to use it. And this is a, you know, you don't necessarily need this literal website, people just click around but an API, you know, because it's for another developer, you want, you know, first for example, if you're building a Django rest framework back end, and then there's a front end engineer who's someone else who's going to be consuming it. You need to tell them, what's what,
Carlton Gibson 18:50
yeah, what parameters are available, what endpoints are available, what HTTP verbs are allowed, what methods are allowed. All of these things need detailing in Back in the day, there was this idea of that there would be hypermedia API's that would be self discoverable and self describing. And whilst that's a noble dream, it hasn't appeared. We're left with how can I describe it? We're left with API's, which each one is kind of slightly bespoke, and patterns like rest and let them be familiar and let them be largely similar. But there is no, there's no automatic way of learning about an API, you have to open up the documentation and look at it and read and write your client for it. So Django rest framework introduced some documentation. So the ability from serializers to generate API documentation. That's all in flux. Now, because over the years, what's emerged is probably the standard is a thing called Open API, which used to be called swagger. And there's lots of tooling and this is this is this. There are other options out there, but this is the key one that's got most of the mindshare and to be honest, at this point. That's the one We need to integrate with. So we're moving from what was a tool, which was called core API to open API. And we're in the process of doing that right now. And we can generate an open API schema now. And that will improve. And that the inbuilt docks, which were built into Django rest framework. Now, they are based on open API. And in the next version, three point 10, they will be deprecated. And then there's another tool called API star, which generates, which is by Tom Christie, who is the creator of Django rest framework. And it's all integrated, that that will take an open API schema, which Django rest framework will generate for you. And then then that's a separate tool to build up generate the doc site. So for the next release, that will all be documented and how you how you use API staff, and the tools will be in placed to implement that, but that will be part of the three point 10 Django rest framework.
Will Vincent 20:53
And when's that coming out? are ones that
Carlton Gibson 20:55
aim for that is April so you know, it's always liable to slip But oh, but only by a matter of weeks, not by a matter of months.
Will Vincent 21:04
And then API star also has async. Stuff included,
Carlton Gibson 21:08
right? No. So okay, so now, API star is the tooling suite around API's. And there will there's a client that will be involved. But the async stuff is a framework could start at which time Chris has been working on. That's what, okay, that's great. And so that, that is a how to describe it. That's a kind of micro framework for general using Python in an async async. Python to build web applications.
Will Vincent 21:38
Right. So just as Python three has a sink, which Python two didn't in Django itself, and 3.0 is going to later this year is going to start some work down the
Carlton Gibson 21:48
road. exactly when Django has a basic support is, you know, an open question because it depends when he's finished.
Will Vincent 21:55
Yeah, yeah. As with all things Yeah. There's, I think, it's also Worth quickly mentioning graph QL. Which if you're learning about API's, today, these days, you're likely to hear about graph QL. So graph qL is different. It's, it's different than rest. I'll take a shot and then you can try to explain it. You can use it with Django right now, there are a number of packages. It's a little bit early days, I would say, but it's very usable. And so why would you do this. So there's a little bit of waste with a rest framework. For example, if you want, you have to do three separate calls, for example, to get a user to find their posts, and then define their followers. So that's three separate call response call response over HTTP, which has headers. And so it's a little bit expensive, with again, because each of those is a distinct API endpoint with a rest framework, whereas with graph qL, that all can be included in one query. So it sounds like a magic bullet of just the front end person can specify what they want and then just get it you don't get you don't waste Seeing, you know, hitting an endpoint with all the users if I only want one. But I would say we're not quite there yet. But, you know, if it does what it says it does, and it, then it will be the future, but I think it's a ways off.
Carlton Gibson 23:13
Yeah. What do you think I have? Like, yeah, you've described it very well. So the exciting thing about graph qL, I think is that in theory enables clients to create their own query, they can specify what objects they want, and what fields they want. And
Will Vincent 23:30
right back to the back end, right, they don't need a custom API endpoint for every little tweak that they want, which can drive, you know, a back end engineer a little bit crazy. So that's, that's another nice thing saying, Oh, you just, you just say what you want. I don't need to customize everything for you. But there's a cost to that. And it still
Carlton Gibson 23:47
has to come out of the database. And there's still problems where you end up triggering the n plus one queries, ie, if there's a foreign key to an object, it not only looks from an object, it not only looks at the object, but all of the tools And he has an you can end up Yeah, very expensive queries. And then those have to be hand optimized. And it turns out at the state of tech that we have today, that the back end engineers doing just as much work getting the graph qL endpoints to run efficiently as they're creating. So at this stage, I have to describe myself as a bit of a graph. qL skeptic at this stage. Yeah, for me, what I like to do is I like to create a utility endpoint, which if I need a nice nested, rich response, which has got the user plus all their posts from the last week plus a follower count, I create a utility endpoint which fetches all of those and then returns those as a as a single package. So the client still only making one call, but it's making it to a utility endpoint, which is easy to craft, and it's done on the back end, and it can be optimized. And for me, the really exciting thing about all this async Python stuff is these kind of proxy endpoints? Because Yeah, they're nice and lightweight. And the async stuff really can get a benefit there, which I don't necessarily see in the more traditional endpoints, so to speak at this stage again, I like an endpoint like that.
Will Vincent 25:18
Yeah. Yeah. It's good to know the costs. I mean, I, you know, my, so after I gave my talk at Django con, I was asked for advice. And I, you know, I don't I'm not currently working on a project at scale. So I'm not sure how, how, if it's my place to say so but I would say I would not change an existing project from rest to graph QL. If you have a new new field thing and you want to try it out, I would say give it a try. But I wouldn't do it on a major project. And I certainly wouldn't switch something over to it because I think, I think maybe people aren't aware of that proxy endpoint approach to that you're mentioning. Yeah, I've read a number of about that.
Carlton Gibson 25:56
But what I'd like is just NGO to bring it to get at least async in the view layer, so that it was easy to write these kind of proxy endpoints in Django itself. And then it'll be super derived blog post about that.
Will Vincent 26:11
Yeah, so the takeaway is, rest isn't dead yet. There are lots of tweaks, there is a cost to graph QL. But it is a very cool technology. And I've seen some really mind blowing demos, but it's a work in progress.
Carlton Gibson 26:25
So I'm like, you know, this wave of technology as it advances and they always say that you want to be slightly boring and certainly conservative if so in some of your choices for me, graph qL is just a little bit too near the breaking edge of the wave at the moment for it to be jumped on to for a major project. Yeah, yeah. For me, for me, so.
Will Vincent 26:45
Yeah, yep. So how does one learn this, Carlton? There's the official documentation. What are you often asked this question, are you more like high level dealing with the pros making, making, you know, commits to it
Carlton Gibson 27:02
Most people who come on to the GitHub issue tracker, already have used it. So because I hang out there that I don't get to answer a question about how I learned this, but yeah, the official tutorial, I always say, look, go to the official tutorial, you've we've talked about in previous, a previous episode about how it can be a bit high level if you're an absolute beginner. But if you you know, if you're intermediate, if you know your stuff, then go through the tutorial. And by the time you've done that, you'll have a good idea of the of what rest framework can offer. And then start building your app, start building your endpoints, and just try. And for me, the, the, there's certain patterns or anti patterns that I see where people put too much logic in views, or they're not extent using the serializer API in the right way. I think you've got to learn those with time but ask questions. There's a mailing list and Stack Overflow again is all the other resources. But just try it out. We'll, we'll link to the mailing list. And yeah, in terms of
Will Vincent 28:01
Unknown Speaker 28:56
which is a pull down. Yes.
Carlton Gibson 28:58
Will Vincent 29:10
yeah, there's something to that. I mean, react in particular is changes dramatically. So if I had to give advice, which I would be hesitant to do, I would say pick react or view, knowing that they change really fast. And you just need, I would just recommend sticking with one for a while. When you're a professional developer, often you'll be on a team and you won't have to do the back end and the front end the challenges if you want to, you know, build a blog with Django and react or view, you kind of have to learn all this and there. As far as I'm aware, there isn't a great guide to all that because it's really two, three separate things. It's Django with API's, and it's the front end framework of your choice, it's too so be aware that it's too much so you know, be aware that just knowing how to Do API's is a huge skill. And while it's fun to try to do stuff with front end frameworks, that's real, there's a reason that's a separate job.
Carlton Gibson 30:08
Will Vincent 31:23
Carlton Gibson 32:38
you're looking at, you know, half a dozen people on the back end half dozen people on the front end, and there's no way you're building it all yourself and somebody who is a is a react specialist. And they their whole job is building that front end and getting that right and to expect to do that and do the API and you know, and deploy it. Yeah. And
Will Vincent 32:59
it's just You're gonna be swimming in the deep end, and you're going to be confused. So that I'll link to I gave a talk at Django Boston last year talking about how to use Django and react together. And actually, in my book, I do give an example of how to add react, which is the same way you would add a front end framework. So there's a little bit there. But it's very rare to find something that covers both an API and a front end, because they're different worlds, and they move so fast. So just be aware of that, when you're learning this. Be aware that maybe you want to, you know, don't blame yourself if it's confusing, because he's confusing for the pros as well.
Carlton Gibson 33:32
And for each project, decide is this a learning exercise? In which case I can be more experimental? Or am I am I trying to ship a product? Because if you're trying to ship a product key, be conservative stick behind the curve, go with the known technologies, and you'll get further.
Will Vincent 33:47
Yeah, hundred percent. So let's try to wrap up here. So how can companies help support Django rest framework?
Carlton Gibson 33:55
Okay, so they, they can sponsor it right. And so, Tom Christie runs a company called encode Io, which is open source, sustainable open source software development, and you can become a sponsor of that. And you can get your logo on the front page of the check the rest framework docs, and you can get some some publicity from that, especially if you're Hi, I
Will Vincent 34:14
see the world that's useful. I see companies on there all the time that I didn't know or Django shops that I, you know that I think that's the number one way to hire a Django developer, I would say is to sponsor Django rest framework, because chances are, if they're doing Django, they're doing back end work, which means API's and everyone is checking that site, the official docs all the time. Yeah. And then it gives you a good
Carlton Gibson 34:39
profile boost within the community.
Will Vincent 34:41
Yeah, it's good karma because there's many more people using it then sponsoring but even more than that, it's more than good karma. It's good business in that you for a very, for very small time.
Carlton Gibson 34:51
If you know if you're a company of any size at all, you've got payroll every month, and for a very fraction that for loose change. Basically, you can add to the system. stainability one of your core dependencies. And that's the costs. You know, there's nothing that's that's just good business. Yeah. Anything else we want to mention, will sponsor the Django Software Foundation as well?
Unknown Speaker 35:14
Will Vincent 35:18
All right. Well, as ever, if you have questions about this episode, please let us know on our website Jango chat.com. Give us inspiration for future episodes. And we'll speak to you next week. Okay, bye bye. Join us next time.