Transcript: Django REST Framework (Replay)

I'm Carlton Gibson and I'm here with Will Vincent.

Hi.

So as you mentioned, it's it's how one builds APIs.

So we're gonna talk about why would you why you would do that and get into the specifics of uh Django REST framework.

What what's an API?

And the key difference between a you know a website, a traditional website has all sorts of things.

It has HTML, CSS, JavaScript, all working together within Django to give you a web page.

An API is just the data.

Um, so you often have to combine that data with those other HTML, CSS attributes.

But why why don't you give it a shot?

I don't think that's the clearest explanation.

So you would encode form data in JSON, send it off to the server, the server would give you back some other JSON, and then you'd use a bit of JavaScript to put it back into the DOM.

And then from there, the other the other big thing that came up was mobile applications, which aren't necessarily web-based.

And so they want to talk to a server, but they they send off JSON, or normally JSON, it can be any encoded format, but they send off JSON, they get JSON response back, and then they use that to update their their user interface somehow.

So it's like a as you said, a data-only communication between the server and the client.

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 would be an internal API, so an API only that Instagram programmers or applications can use, they can all speak to one another, and 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 know, 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 gonna switch to an API.

So if you want to build an API with Django, what are you gonna use?

You're gonna use Django REST framework.

So what's REST about?

What's the REST bit?

Django is a framework, it's a framework's a toolkit, but what's REST about?

So REST, here's another acronym, represent uh representational state transfer, which I don't just like application programming interface, I don't think is that helpful.

It is an architecture style, um, only from the year 2000.

Uh Roy Fielding did it as his dissertation.

It's basically a set of rules or suggestions for how to structure an API so there's some continuity to it.

Uh there's and really what it does is it makes you learn HTTP, hypertext transfer protocol.

That's right.

HTTP, yeah, I look up in your browser and you'll see HTTP or probably HTTPS.

The S stands for the encrypted version.

So because we're on the web, you can build APIs for any, you know, anywhere, but because we're in a web context, we're using HTTP, which is the way that information is sent back and forth.

And REST has a number of properties that make something RESTful or not.

So that would be there's a client-server relationship, which is what you have on the web, a database talking to uh a user.

It is stateless, which there's much we could say about that.

So each request is independent, which means that it's okay if a message doesn't get all the way through, but it makes it harder to know things like is someone logged in, or has something changed to a shopping cart?

You know, dealing with state is really probably the fundamental challenge, I would say, of the modern web.

Um it's cacheable, uniform interface.

There's really a whole list of restful things, but generally, you know, and I guess I would add on top of that, when you're using it, you're so if you think of a web page, a web page just gives you the HTML CSS JavaScript.

You have a what's called an API endpoint.

So it's also a URL.

Um, and it'll be something like, you know, so if instead of Google.com, it'd be api.google.com, and at that endpoint, you can use HTTP verbs, or excuse me, methods, well, methods, verbs, same thing, um, such as get, post, push, put, delete.

Like these cor this is the key point for me, is like all the other stuff, the stateless and whatever.

Yeah, it's kind of interesting, but the key point for me is that the the the HTTP verb H how many T's was that?

The HTTP verbs correspond to the methods of CRUD basic uh as normally understood.

So you get to retrieve a resource, you can post or put to create or update, you can delete and 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.

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.

Um I think it you know, 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 APIs, you will get that.

Um I 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.

Um it's really when you build an API that it will become real to you.

I I mean, you know, that that's all very abstract, but what does Django Rest framework give us, DRF?

What does DRF give us?

So right, so Django, Django Rest framework.

So Django, you build a website and you say, right, I want an API.

Django Rest framework's 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 as really the magic, which will transform, instead of sending a web page 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.

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 a create retrieve API view, like the combin combine these.

You'll see that's built upon Django itself.

Uh so I definitely recommend building a couple.

If you if someone says to you, or your boss says to you, go build an API with Django Rest framework, build a coup 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.

And then on top of that, you just put a view in place, and then the framework bit of Django Rest framework, it 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.

Right.

So the so you have your model, you have your URLs, and then and 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.

You'd 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 advanced.

Um we should mention, I mean, you are a core maintainer of Django REST framework, so you know that of which you speak.

Right.

Certainly more so than I do.

So um I was building uh iOS apps um for in a in a freelance environment and agency environment, and um clients needed not only an app, they needed an API to go, they needed something for the for the mobile application to talk to.

And I knew Django, and so I was like, well, I can build the back end, and and looking for some a tool which enabled me to build APIs with Django, and Django Rest Framework popped up, and 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.

There's it's there's too many t issues to triage, there's too many questions on Stack Overflow, the mailing list is too hard.

So I got onto the mailing list, I got onto Stack Overflow, and I started answering questions and helping out.

And all of a sudden, Tom's like, Oh, you know, you're here, you can be a maintainer on the framework, and I'm I'm closing tickets and merging pull requests, and it's all you know, and that was that was how I got started in open source was it I was using Django Rest, 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.

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, even though you'd already entirely.

If you just use it, you'll go, oh API is not so bad.

You know, standard functionality.

Uh, you know, it's it's really I don't know how much, you know, there's a benefit in learning how other things are harder, but Django Rest framework is about as easy as it gets these days to build a powerful, secure website, uh, excuse me, web API with a minimum of code.

I haven't seen really anything that comes close.

Maybe, maybe Ruby on Rails, but maybe.

And then when something's difficult, we complain.

Oh, this is hard.

Yeah.

Um, so what else does people need to know?

So authentication is a big one as well with APIs.

And I actually did a DjangoCon talk, we'll link to all about this, um, which was actually where you and I met in person for the first time, I think.

We'd we'd spoken online.

So with authentication, so Django itself and most web frameworks use sessions where you have an ID that is created um for the user and then stored on the server.

I'll link to the docs on that.

We could we'll we'll probably do an entire episode on authentication.

When you're dealing with an API, you can also use tokens as well as JavaScript web tokens.

So instead of passing a session object back and forth, you're passing a token.

There's a whole number of ways to do this.

And again, the the talk I go through and I give full examples of the main ways to do that within Django.

But this is a big sticking point for people.

I think after understanding serializers, authentication is what really hits people because you have to understand how HTTP works to understand authentication.

Yeah.

Which which is that HTTP, and please correct me on this, but HTTP contains header, body, and a message typically.

So the and the header is where the information like authentication is included because that is passed with every request.

And because HTTP is stateless, you have to include it to otherwise you can't be sure that someone is who they say they are.

Well, it's because they have the same token or the same identifying feature.

It could be a cookie, it could be um a token, as you said, of some kind.

Um and that's the key, right?

It is HTTP, the underlying protocol, is stateless.

So it has no concept of a session.

So we have to put this on the page.

You have to have that cookie.

You have to log in and the cook and 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, right?

So look like you're doing it in that example that I gave at the beginning of uh enhancing a form submission with Ajax or anything where they're in the browser, just use SessionOuth.

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 um JWT or AOAT tokens of some kind.

It's the you know, if you go to the official uh page, there's there's a reason why there's tons and tons of pages to do this, partly because the technology around this is a changing space with JavaScript web tokens and other in OAuth for for social authentication.

So it's unfortunately it's a bit complex right now for everyone.

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.

Well, no, right, because Yeah.

Another key point when you're learning about APIs and REST, Django REST framework is the concept of cores, C-O-R-S, 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, I 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.

It's Django

Course headers, which is super important.

It can't do that without setting the right headers, the right courses.

It's sort of secret, secret information that's really important, I would say.

Documentation, what to say about this, Carlton?

Because you know, an an API, you need to have a roadmap to understand so someone can understand how to use it.

And this is a you know, you don't necessarily need this with a traditional website, people just click around, but an API, you know, because it's for another developer, um, you want, you know, for example, if you're building a Django REST framework backend, and then uh 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.

All of these things need detailing.

And back in the day, there was this idea of that they would be hypermedia APIs, that would they'd be self-discoverable and self-describing.

And whilst that's a noble dream, it hasn't appeared.

Um we're left with well, how can I describe it?

We're left with APIs 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.

Um that's all in flux now because over the years what's emerged as 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 mind share.

And to be honest, at this point, that's the one we need to integrate with.

So we're moving from what was um 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 but the inbuilt docs which are built into Django Rest framework now, they are based on OpenAPI, and in the next version 3.10, they will be deprecated.

And there's another tool called API Star, which generates um, which is by Tom Christie, who's the creator of um Django Rest Framework, and it's all integrated.

And that that will take an open API schema, which Django Rest framework will generate for you, and then that's a separate tool to generate the doc site.

Um, so for the next release, that will all be documented at how you how you use API Star and the tools will be in place to implement that, but that will be part of the 3.10 Django Rest framework.

Or when's the S?

And and then API Star also has async stuff included, right?

Um there will there's a client that will be involved, but the async stuff is um a framework called Starlet, which Tom Christie's been working on.

what I'm saying.

So just as Python 3 has async, which Python 2 didn't, and Django itself and 3.0 is going to later this year is going to start in some form down the async road.

Yeah.

Uh there's I think it's also worth quickly mentioning GraphQL, which if you're learning about APIs today, these days you're likely to hear about GraphQL.

So GraphQL is a different, it's it's different than REST.

Uh I'll take a shot and then you can try to explain it.

Uh 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.

Um 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 to find their followers.

So that's three separate call response, 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 GraphQL, 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.

What do you think?

Like so the the exciting thing about GraphQL, I think, is that it in theory enables clients to create their own query.

They can specify what objects they want and what fields they want.

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.

iciently as they were creating so at this stage.

I have to describe myself as a bit of a GraphQL skeptic at this stage.

Um for me, what I like to do is I'd like to create a utility endpoint, which if if I need a nice nested um rich response, which has got the user plus all their posts from the last week, plus a follow account, I create a utility endpoint which fetches all of those and returns those as a as a single package.

So the client's still only making one call, but it's making it to a utility endpoint which is um 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 that they're nice and lightweight, and the async stuff really can get a benefit there, which I don't necessarily see in the the more traditional endpoints, so to speak, at this stage again.

Um I like to create an endpoint like that.

Yeah, it's good to know the costs.

I mean, I you know, my so after I gave my talk at DjangoCon, 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 um if it's my place to say so.

But I would say I would not change an existing project from REST to GraphQL.

If you have a new a 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 too that you're mentioning.

Yeah, perhaps I didn't want to post

Um but the what I'd like is Django to bring it's um 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 to write a blog post about that.

There are lots of tweaks, there is a cost to GraphQL, but it is a very cool technology, and I've seen some really mind-blowing demos, but um it's a work in progress.

For me, GraphQL is just a little bit too near the breaking edge of the wave at the moment for it to be jump onto for a major project.

Yeah.

For me, for me.

So how does one learn this, Carlton?

There's the official documentation.

What are you often asked this question, or are you more like high-level dealing with you know the pros making you know commits to it?

So because I hang out there that I don't get to answer questions about how I learn this.

But yeah, the official tutorial, I always say, look, go through the official tutorial.

You we 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 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, there's Stack Overflow again, there's all the other resources.

But just try.

And yeah, in terms of so I wrote a book on this last year in part because at the time I wasn't aware of any books on the topic.

There have since been a couple, which we'll link to, but you know, my book's a good resource.

The first couple chapters are available for free online, RESTAPIs with Django.com.

I think the challenge when you're learning is you build the API, and then if you're building something solo, then you need to know a JavaScript front-end framework.

So that's you know, you need to know JavaScript, you need to know the front-end framework, you need to learn about how to pass like the auth tokens back and forth.

And so I'm often asked which which one should I choose?

Which is a tough thing to answer because you really just need to pick one and go with it.

If you know someone came to me, total, totally said, which which one should I learn?

I don't really know much.

I would say the big three are React, View, and Angular right now.

There's also Ember.

There's some other ones.

fan of Elm, which is a whole different approach.

Yes.

Like, but I love that.

I love that mainly because it keeps me out of the whole JavaScript churn battle.

I can just stick with Elm and I don't have to worry about what the latest changes in JavaScript land are.

I mean, uh React in particular is changes dramatically.

So if I had to give advice, which I would be hesitant to do, I would say picked React or View, knowing that they change really fast.

And you just need, I would just recommend sticking with one for a while.

Um when you're a professional developer, often you'll be on a team and you won't have to do the backend and the front end.

The challenge is 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, it's APIs, and it's the front-end framework of your choice.

Yeah, it's too much.

So be aware that it's too much.

So you know, be aware that just knowing how to do APIs 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.

Yeah.

So you can focus on the API or you you'll on the front end and you you the the interesting discussions you'll have exactly what the endpoints are and what the data transmission formats, what the JSON looks like.

Like that that's all great stuff, but you won't be building both bits.

If you're building a solo project, I'm gonna end up sounding like an old man in here, but like, do you really need an API?

Like, can you just get away building a Django site which does a static request response return, renders the page on the server, gives you back the page, and then sprinkle on some JavaScript and the odd API endpoint just to enrich it a little bit.

But to drop, as a solo developer on a solo project, to drop everything to go for this single page, full front-end thing, I think you're just biting off well way more than you can chew.

Um if it's just if it's a learning exercise, no problem.

But if you're trying to build it as a viable, actually get something done, consider the traditional approach.

It's not it's not so bad.

In fact, you if you get something built that works versus not get something built that works, it's much better.

It's well that as with so much technology, the challenge is how do you iterate on it?

And I I also urge that caution.

Try it out, but do you really certainly a solar project?

Do you really need an internal API?

Yeah, think about it, and maybe you just need a couple, a couple, a couple things, not the entire site to be switched over.

Um it's a it's a challenge.

I mean, I I was one of my takeaways from DjangoCon last fall, which is my first major Django conference, was it struck me that most Django people don't know JavaScript well at all.

And that's because they don't need to.

Uh I've worked more very early stage, I've worked on solo projects, so I'd say I'm intermediate level with JavaScript.

And I was feeling, wow, I'm surprised these folks don't know JavaScript better, but it's because they know Django and Django Rest framework and all the rest of that, I'm sure, much better than I do.

It's really, you know, once you once you go in a professional role, you're gonna you're gonna be specializing.

Um and yeah, for a solo project, keep it simple.

No one cares if you have an API or not on your project.

And there's a reason why teams work on this stuff.

It is a lot of work, even a simple site to have it be super smooth and fast and performant.

Yeah.

And there's no way you're building it all yourself.

And that somebody who is a is a React specialist, and they that their whole job is building that front end and getting that right, and to to expect to do that and to do the API and you know and deploy it, and it's just not feasible.

So that I've 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 it's confusing for the pros as well.

Because if you're trying to ship a product, keep be conservative, stick behind the curve, go with the known technologies, and you'll get further.

So let's try to wrap up here.

Um, so how can companies help support Django Rest framework?

And so um 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 um Django Rest framework docs, and you you can get some some publicity from that, especially if you're hiring in the Django world that's useful.

If you know, if you're a company of any size at all, you've got payroll every month, and for a very fraction of that, for loose change, basically, you can m add to the sustainability of one of your core dependencies.

And that that's that costs, you know, that's nothing.

That's that's just good business.

Yeah.

Yes.

Yes.

Well, as ever, if you have questions about this episode, please let us know on our website, DjangoChat.com.

Give us inspiration for future episodes, and we'll speak to you next week.

Join us next time.