[Music]
to yure 2 with three Jango talks the
first one is called Jango rest and Open
PI a gentle
introduction and it's by Paul
waer um I hate glasses uh Paul is a six
foot tall ape descendant and nobody is
currently trying to bypass through his
home he works for an open source company
and in spare time he maintains websites
rides electric motorbike teaches Iris
set dancing plays the piano reads
Science Fiction and Fantasy 3D prints
and collects esoteric Hobbies I wish I
had that
much welcome to your talk thank you
thank you and greetings from Nal country
where I come from um I have been
programming for a fair while uh which is
why I use boring uh default uh Libra
office impress templates uh and
currently I work at a small uh open
source company that few people have
heard of uh working on an API that only
our customers can actually access uh so
instead I thought I'd do my demo on one
of my other Hobbies uh which is mixing
electronic music um and I published them
on uh my website uh each mix has a list
of tracks uh is distributed through a
number of files and can be linked to one
or more Styles so I want to provide um
an API for that uh so I'm going to
assume that you know mostly about Python
and Django uh and on the other hand if
you already know a lot about Django rest
framework uh open API uh and using that
um the exits are there um I'll be
leading the way um so let's talk a bit
about what apis actually are uh a good
talk on Friday I think by Ash said that
uh rest is a really overused term and it
probably doesn't mean what it used to
mean basically all we're talking about
here is an interface for programs to
read data from something you publish
usually a website um so that means that
the data is going to come not in a nice
template
um the camera crew really wants me to
stay in one place so I'm going to have
to fight my instinct to point all over
the place um so the um
uh the programs are going to read this
uh output so it's going to be in a
standard format uh it's not going to be
rendered nicely in HTML and things like
that uh and in Django we have standard
methods of doing this you've got models
which store the data uh and then those
views um get referenced through the URL
grab the data from the models and
present it in templates D Jango rest
frame work works very similarly the only
real change is that we use serializers
instead of templates uh and I'll cover
those in a sec so for my website uh if
you go to mixers uh you get the list of
all the mixers and if you go to mix
number one you get the first mix that I
produced uh and if you go to
mixstyle
SLR then you get all of mixes just of
that style and we want to Pro provide uh
the mixers API um which lists which has
sort of very similar things we have a
list of mixes and we want to publish um
details on mix one and so we've all
written view code like this um grabbing
all of the mixes the latest news the
last data mix was completed um and
render that using a template uh likewise
um
mix details uh this is where we get a
bit complicated and we might want to
change this at some point because uh
mixers have a number but they can also
have multiple Parts I some mixers I did
two parts on the same day uh some mixes
I have gone back and reworked and so the
rework is mix
1.2 um so we've all written view code a
bit like this now one of the things that
I really love about Jango Jango and I
think more Frameworks out there should
embrace this principle is don't repeat
yourself but we seem to have written
that code a lot for view list views and
detail views and search views and you
know create views all of those sort of
things it's the same code over and over
again and so normally when we go through
this Evolution uh we get to we start
writing our own views and then we find
out that someone's done this before so
we get generic views and then we we hit
the limitations on generic views really
quickly uh and usually we get told yeah
actually you have to go back and
reimplement all of your
stuff so Jango rest framework has uh an
idea called view sets um I'm going to
talk about that uh as one of the
fundamental things to take away from
Dango rest framework what do they look
like like so here's uh a really basic
view set that I wrote um for mixers um
we're using the readon model view set so
that um will introspect my model I just
tell it the query set that I want to
look at and then the serializer class
that is going to take that data and
present it to the outside
world that's it that has all the inbuilt
code to handle the list View and the
detail view it's also got all the
inbuilt code to say if someone tries to
say create a new mix and this is a
readon model view set um then they get a
405 method not allowed also really nice
if I want to change uh how that mix set
is um presents its detail so instead of
the um number I want to present a much
more readable slide
all I have to do is just add the lookup
field Slug and that will know to get the
right field out of the mix qu the query
set when it's looking for that detail
view all the 404s everything handled
just fine that's really really
compact so let's talk about that
serializer that I was kind of glossing
over before
um D Jango uh we have template to Output
data from the internal representation
out to the outside world and we've got
forms to take data from the outside
world and turn take it into our Jango
model template so for um Django rest
framework the serializer does both of
those functions what does a serializer
look like well here's the mixed
serializer and we give it we based on
the model serializer class uh we give it
the model and we tell it which fields we
want to
Output
um the complication here remember I
talked about that number and part those
two Fields aren't really completely
independent we'd like to present them as
one thing um there's a couple of ways we
can do that one is we can take the
describe the the field a bit more and we
can use a serializer method
field um that looks for a get uncore
field name method in the serializer uh
and then outputs the number or the part
if it has a part but that's only read
only we can't um put data back into that
so instead what we might do if we want
to uh input at some point I might
actually like to have an external
program create these things for me
um we Define our own field and the all
the field really needs to do is do two
things one is take the internal view the
internal mix and um output the
representation we want the external
world to see the other is uh taking the
external representation and using the
magic of regexes and named Rix
um Fields uh uh and group dict uh we
just return a dictionary um if we got a
match uh and that dictionary contains
the number and the part Fields uh and if
we didn't match then there's some kind
of validation error so raise that and
that's all we need for our mixed number
field we just make sure that we
reference mix number in the fields list
um as opposed to the number and the
number and part Fields like likewise uh
we can have a track
serializer um that just is based on the
track and outputs the number and artist
and title and we can include that track
serializer as a field in our mix
serializer We Tell It many equals true
which means that that is going to Output
a list of fields not just a single field
and we give it the source which will be
the foreign key relationship from the
mix if you're you're doing uh in the you
know Django uh you've got Django shell
uh and you do mix. track set that will
give you the query set of tracks within
the mix um so that's the that's the
source we're looking at that's all I
need to do to include all of that data
as a su list in my actual
mix that is really convenient I have to
say Okay so
um we've got our mix view set um how do
we actually present that to the outside
world so in Django uh we would uh create
the URLs list uh as a list of paths um
which link the actual um text fragment
to the view method or class um and that
looks something like this so we have the
index view um based on the blank path um
linking the to the views. index function
uh and they're named so we can refer to
them in tests uh likewise we have two
linking to the mixed page depending on
whether we got a number or a number.
part in D Jango rest framework this
works slightly differently um we it has
the concept of a router and routers
gather view sets and they can enumerate
the um methods provided by that view set
and turn them into
URLs that in your code will look
something like this so we import the
routers uh we create a simple router and
we register against the mix path
fragment uh we register the mix view set
and then we just include that router.
URLs in our API path
um because I've been doing this a while
and I don't do live demos very well um
this is the copy and paste of my live
demo um and that uh query basically so
we mapped mix and then it looked at yes
there's actually a part after this so
this must be a detail view that's the
slug that we gave it
it takes the slug puts it into the um
query set finds a single item so we
didn't get a
404 um gets that item feeds it through
the serializer output outputs
that um the so the view set and the
router has known how to map all of that
path information back into uh an actual
query and we haven't had to spell that
out at all uh so that works for the the
list view works for the detail view we
can also add extra actions so here we
use the action decorator um and we tell
it at detail equals false we're going to
return a just the mixes and a random
order I don't know it's a demo um and
here we need to do a little bit more
work uh this is not um a simple thing um
in terms you know compared to just using
the default list output but all this
this is what your standard this is sort
of the list or detail um methods would
look like this so U they start with the
request um we're going to return a
response object we get our serializer we
give it the query set that we want it to
serialize We Tell It many equals true so
that it it will output a list and then
we ask for the data out of that
serializer
the response then feeds that through the
renderer to Output Jason or yaml or CSV
or whatever um and so out out of that um
comes a chunk of
Json but most
importantly when I add that I don't have
to change the router or the URLs at all
the router automatically introspects
finds that action
adds that to the set of paths that it
recognizes that is don't repeat
yourself okay so where was I up to we
need to talk a bit about uh
authentication um this is a little bit
more complicated these are the things
that I found myself stumbling over a
little bit um but if we wanted something
where I could um write a program to add
new mixes um but everyone else just sees
standard view um we there are two phases
to Jango rest Frameworks sort of
authentication permission system one is
the authentication so it looks at the
request you've made sees if there's any
uh information in there that
authenticates you grabs that tries um
tries to see if it's valid uh and then
if it is one of those authentication
authentication classes will return and
your request object will now have an or
property which has the authentication
information in
it um the permission
class uh then checks which of the
whether you're actually allowed to do
the request that you have asked to do so
here I'm using the standard is
authenticator or if is authenticated or
readon permission um does kind of what
it says on the tin um there's only one
authenticated user on my website and
that's me so that's really simple I
didn't have to work out who uh who else
was allowed to see uh or create mixes um
OB if you are if you need more
information uh in your permission class
about exactly who is allow allowed to um
access exactly what you'd modify uh your
own permission class the trick with
permission class is where where the
authentication class the first one of
those to authenticate wins and it says
yes authenticated uh the permission
class um if the if any one of those
returns false then you're
denied uh you can actually a and and
these together which is pretty neat U so
you can make a combination of permission
classes um but the idea with your
permission class is that if there's if
it if it doesn't say
yes then and it says no Then whichever
one of those uh says no will win and
you'll get
denied okay testing um there's not a lot
to say about testing everyone here is
obviously uh doing all of their tests on
their Dango um systems so the only real
thing that I want yes I lots of heads
nodding thumbs up yeah agreed um so the
only thing I really want to point out
here is uh the reverse name um that has
been created by the router out of the
path fragment that we gave it um or a
base name if we supplied that and the
view name so list handles lists details
handles detailed View use
um when we um post to if we want to
create uh a mix We post to the mix uh
list View and so that's kind of uh how
that it's not named mixor create at that
point um but those names come for free
again we don't repeat ourselves that's
nice as well
okay so open API uh what is it um it
used to be called Swagger um and it's
basically in the same way that apis
allow programs to talk to your
um website and get information um the
open API standard allows the program
talking to you to see what that data is
going to look like what queries it can
um give make on your you know what what
creery parameters what the uh example
data that you might Supply looks like uh
that often is supplied as yaml uh here's
an example um and it basically lists the
paths uh combined with a
description um which you might
recognize um from the model that we
um uh from what the model we supplied
and then it lists content it lists a
whole bunch of other stuff don't worry
too much about
that uh so I'm using the uh package drf
spectacular um there used to be an old
one drf YK uh they only coped with open
API 2 uh spectacular is the three
variant um that you need a little bit
more setup you um install it and then
you need to plug in um the spectacular
settings in your settings Pi file uh the
main obviously fill in your title and
description uh don't use mine um the
main one to point out here that I really
like is serve public normally that
defaults to true what that does is it
will uh when you request the open API
schema you it is you see every
possible
um method every possible path every
possible
um uh serializer information that that
would come out of your website when you
set that to false the view the user gets
of your open API schema is what they can
do on the
website which means you if you're
providing a Reon schema to
unauthenticated users they don't get
confused as to why they might be able to
post or delete website and they don't
get confused when they then get told no
you're not
allowed okay we also need to plug in a
couple of things in our uh this is my
main uh root paths file so we've include
the mixers URLs and we just include we
use the spectacular API view um and then
we uh use if you're using the Dango rest
drf spectacular sidecar package you get
a Swagger API for free um you include
that and you point it to the URL name
that we declared for the other uh open
API
URL uh and that allows us to generate a
nice content and because that is a demo
this is a demo um it gives you this nice
uh spec that you can go in and try these
things
out so there's lots more uh information
this has really just been a very basic
introduction to how to use uh Jango rest
framework Dr spectacular those are the
bits that I stumbled most on um thank
you very much for your
time thank you very much Paul about um
but uh that's just that's why we have
those two particular views uh if you
don't want to provide that particular
output you only use the first open API
schema and that's all you need to
present cool we have time for one more
question up the back
there hi thanks for the talk let's say
you join a hypothetical company and they
give you ajango app and the view.py is
6,500 lines long what would you do to
dry it
up I that is I'm totally sympathetic to
that particular situation um so that's
where I what I really like and the
reason I approached this from the point
of view of um taking my existing website
and adding an API to it is it's really
easy to just bolt on that uh mix view
set use the router and get a simple
output um and you can supply that as uh
say SL API
slv2 and now you can do ab comparison
between uh version one and version two
of your API to see if the queries match
and the responses match um and I would
just chisel away gradually adding mixes
sorry adding um models adding view sets
one by one um so don't try to do a whole
don't try to replace the whole thing in
one go just um add little bits at a time
and the fact that uh for example with
the track list
um the that I can add that as a single
field that gets expressed as a a list
within the Json output there uh means I
don't actually have to try to replace
every single output in that
um uh that big set of URLs maybe I just
need one piece of data that contains all
of the information that a person like or
a a script like the UI would want to
know about that
mix so see yeah again uh I like the the
approach of try to do as little as
possible in that sort of situation see
how uh see how
few um view sets you can use to Pro
provide the information that your
customers
want thank you very much
[Applause]