Most Restful APIs build with the very popular Django Rest Framework. The general use case of the Django Rest Framework is to build private or public APIs. The Framework is actually a package that can extend the existing Django functions and make it easier for you to create those standalone API.
How does Django work?
I am going to assume here that you already know the Django framework. But in case you don’t then Django is a great web development framework build on python which can handle both small web apps as well as large enterprise apps. Some big name companies are using Django for their applications, like Robinhood, Instagram, Zapier and Disqus!
Django was build in a way that it uses a similar structure to MVC. MVC stands for Model (databases layout), View (the templates), Controller (the logic). For Django, this is actually MVT (Model, view, template) - the view is the controller with Django. This structure is used to simplify and organize your code. If you have been a few years in the industry (like me), then I bet you remember the days that everything was in the same file. The the database queries, the templates and whatnot. Glad those days are over now.
This MVC standard is great for building dynamic websites. Though, there is an issue with this. With every change and every update you do, it needs to refresh the page. It’s not
reactive based on the things you do.
What’s the Django rest framework?
The Django Rest Framework is a Django package that can be installed in your environment with
pip install djangorestframework (more on that later) and it’s used to build Restful APIs. Actually, you can do the exact same thing with Django without this package. Though, in that case you would be reinventing the wheel quite a few times. The Django Rest Framework package is a huge timesaver as it will set you up with everything you need to build APIs quickly.
That’s all it is, really.
How do we install the Django Rest Framework?
Before you can actually create a Django Rest API, you will have to install it like any other plugin you install for Django. Simply use pip (
pip install djangorestframework) or you can clone the project from Github (
git clone [email protected]:encode/django-rest-framework.git - not recommended).
Then in your
rest_framework in the
Great, Django Rest Framework is installed now. Let’s create the Django Rest API now.
Django Rest Framework tutorial: a very simple API
For this example API, we will create an API around the object Article. It will have a title field, a text field and a date field.
Let’s create the model
Article first. In your
models.py file add this:
With this model, it will automatically add a date when an article is created. Now, we need to create a serializer to make sure that the data gets sanitized and published correctly. if you come from a background with using forms in Django, then you will probably recognize that there is the same pattern with the seralizers.
If not already there, create a
serializers.py file in your app folder. Here is how our Article serializer will look like:
Up next we need to create a view in our
views.py. This is to tell Django what to show exactly with what serializer and what model. Here is how ours will look like:
As you can see we created a
viewset that is inherited from the
ModelViewSet is a set of views that is build to create simple requests to this view. Like
patch (you can overwrite any of these). As you can see, we added a
queryset, which is where the records will be pulled from. In this case, we want to display articles, hence why we picked the
Article model. The
serializer_class will tell what to accept as arguments for requests and what to show when something needs to get consumed from the api.
At last, we need to add a URL to send requests to. Let’s open (or create) the
urls.py and add the following:
In the above snippet, create a
DefaultRouter instance. This is basically Django Rest Framework’s way of telling how to create urls for their
ModelViewSet classes. Up next, we register the
ArticleViewSet we created in our
views.py and give a url (in this case this will create
/api/articles/<id>/). Then we add the router urls to the
Don’t forget to run
python manage.py makemigrations && python manage.py migrate to migrate the model we created and the default django rest framework models
Start Django again with
python manage.py runserver and go to
http://localhost:8000/articles/ in your favorite webbrowser. Voila! We have now a cool API endpoint. You will probably see something similar to this:
You can now also do
curl http://localhost:8000/articles/ in your terminal/shell. It will respond with
 as there are no items in it just yet.
http://localhost:8000/articles/ is now one of the endpoints you can consume to create and list articles. You can also look up specific articles by using
<pk> with the ID of your article.
Django Rest API Settings
You can customize the API quite easily. Simply go to your
settings.py file and add the following dictionary:
In this dictionary, you can add various Django Rest Framework settings. Here are a few that are commonly used
DEFAULT_AUTHENTICATION_CLASSES is a setting that you can use to set the authentication for what users can use to authenticate themselves. For example: you can add
rest_framework.authentication.TokenAuthentication to only allow people with a valid token to view or make changes to the API.
A full example of that would be:
In the above example, we allow users to use either a token or a session to access our API. It will first check for a token and then check for a session in this case.
DEFAULT_RENDERER_CLASSES is a setting that allows you to select how the endpoints are shown to users. As you have seen before, we can now see the API visually with a nice GUI. You can disable that with this setting. Here is a full example of that:
In the above example, we disable the GUI and only show JSON responses.
DEFAULT_PERMISSION_CLASSES you can assign custom permissions to your API. A good usecase would be when you have different kind of users. Let’s say you have a publisher and reader. A publisher should be able to read articles. A reader should not. We can easily deny requests with a permissions file (more on this in the next chapter).
Let’s create a new file called
permissions.py. This will be our file to define permission classes with. A permission could look like this:
The above snipped will deny any requests from users that are not authenticated and users that are not publishers.
Some helpful extra packages you might want to consider
This package will install some other dependencies as well. Then you can extend the package a bit more with the following packages. Those are all optional.
pip install coreapi)
This is a package that will allow you to consume your API as objects instead of standard JSON. If you are not familiar with CoreAPI, then it’s best to ignore this package for now.
pip install markdown)
MarkDown itself is known for it’s ease to style text documents. This can be used to document your API. If you are not planning on documenting your API, then there is no need to install this package.
pip install django-filter)
Django-filter is a library that let’s you filter out fields that you actually don’t want to transfer to your frontend. This can be used to save bandwidth and only send data that you are actually going to use. You can limit the amount of data is send by using serializers, but this package allows you to quickly filter models instead of creating a new serializer.
pip install django-crispy-forms)
This package is really useful when you are using
django-filter as well. With Crispy Forms you can help with displaying filter options in html forms when you are using the GUI interface.
pip install drf_yasg)
This is a very simple library that will build API documentation automatically. This is best to use when you are building an API for users/customers.