Django REST Framework: Get Started Fast

TL;DR Django REST Framework

If you’re not interested in the nuts and bolts of the Django REST Framework (DRF), just jump to the tutorial bit to know how to get your API off the ground in five minutes or less. Afterwards, come back and check out the details of how each part of the DRF tutorial is put together and what additional features and functionality you can get from DRF.

Introduction to the Django REST Framework

The Django REST Framework is like the Django for RESTful APIs. It provides so much out of the box for you that just by installing and hooking it up to Django, you get a ton of functionality without having to write much code at all. For big, complex projects, that’s a huge relief for anyone maintaining that code.

Django REST Framework comes with Serializers that can directly replace Django Forms for api-based validation and object creation, generic view classes to get your API endpoints up and running fast, and an automatically generated browsable API for any of the Django REST Framework views you use.

These are just a few of the great things that Django REST Framework comes with, and just like Django and any other Python package, you can take the parts you want and leave the rest alone allowing you to ease into something like converting your existing APIs to Django REST Framework without having to learn the entire framework.

Let’s briefly look at some of the things that make Django REST Framework so powerful.

Serializers

When I first started working with Django REST Framework, I already had my own APIs built using Django Generic Views and was struggling with serializing the complex data I had. Importing and using the Django REST Framework serializers took all that headache away. There are several different serializers you can use, and you can customize each different type. Out of the box, the serializers handle complex Django model instances with ease and the API for using the serializers is intuitive and well documented.

Django REST Framework serializers are so similar to Django forms, you shouldn’t have any trouble picking them up. Let’s look at a Django REST Framework `ModelSerializer` and compare that to a Django ModelForm:

"""
Forms for Character model
"""
from django import forms

from characters.models import Character


class CharacterCreateView(forms.ModelForm):
    class Meta:
        model = Character
        fields = ('name', 'description', 'profession', 'mentor', 'team', 'type',)


class CharacterUpdateView(forms.ModelForm):
    class Meta:
        model = Character
        fields = ('name', 'description', 'profession', 'mentor', 'team', 'type',)

"""
Serializers for Character model
"""

from rest_framework import serializers

from characters.models import Character


class CharacterSerializer(serializers.ModelSerializer):
    mentor = serializers.StringRelatedField()
    team = serializers.StringRelatedField()
    random_line = serializers.SerializerMethodField()

    @staticmethod
    def get_random_line(obj):
        return obj.get_line()

    class Meta:
        model = Character
        fields = (
            'name', 'description', 'profession', 'mentor', 'team', 'type', 'random_line',
        )

You can see that the definition is almost identical. The differences in this simple example are the StringRelatedField fields and get_random_line method on the CharacterSerializer. These extra pieces are used to add additional information to the serialized output.

The StringRelatedField takes a related model and outputs its __str__ representation when serialized, and the get_random_line calls a method on the model and adds that to the serialized output. DRF Serializers allow you to customize, add, and exclude any data you choose from your serialized output.

Just like Django ModelForms, the ModelSerializer also provides a create and update method, so you are able to create and update model instances through your serializer and API endpoints.

Another powerful feature of Django REST Framework Serializers is that aside from just form processing, they can be used to serialize data in _bulk_. You can serialize entire QuerySets into JSON, without any modification.

Views

Django REST Framework provides generic class-based views that you can just use out of the box. These views will produce both the browsable API and the JSON API formats for you automatically.

The configuration for the Django REST Framework class-based views is almost identical to Django class-based views so you should be able to pick up the syntax immediately.

There are views provided for listing, creating, retrieving, destroying, and updating. These can all be used individually as class-based views and hooked into whatever URL route you want, or pieces of them can be “mixed in” together to include or exclude specific endpoint actions or functionality from your views.

For the majority of your needs though, Django REST Framework did us the favor of combining the endpoints that go together based on the REST spec, giving us the ListCreateAPIView, RetrieveUpdateAPIView, RetrieveDestroyAPIView, and finally the RetrieveUpdateDestroyAPIView.

To go even a step further, Django REST Framework provides ViewSets which are single view classes that provide all of the view functionality for a given endpoint. That’s five endpoints, not to mention the built-in browsable API all for free. That’s brilliant.

So if you’re using Django generic class-based views, you’ll be able to create almost identical views using DRF class-based views to produce your API in the same manor.

The best part is that these views can all be based on Django Model classes, so that as your data model changes, your endpoints will stay up to date without you having to maintain them.

The Browsable API

I’ve mentioned the browsable API a few times already because it is such a gift. Having a browsable API can serve as both documentation as well as a troubleshooting and smoke-testing tool for your APIs. Not having to actually write that documentation saves a ton of time.

The browsable API is also customizable if you don’t like the default formatting or style of the produced pages. There are third party tools that get a lot of attention for doing what the browsable API does; they allow you to query your API endpoints and visualize the data in a clean, even beautiful way. You get that baked right in with the Django REST Framework!

URLs

The way DRF handles URLs is again modeled after Django itself. When you add a view to your project, you need to add a URL route for that view. DRF provides some great utilities to go along with their combined view classes, so the routes are automatically created. By using the provider Router classes, your views will be hooked up and function as expected with very little work on your part

from rest_framework import routers

router = routers.SimpleRouter()
router.register(r'users', UserViewSet)
router.register(r'accounts', AccountViewSet)
urlpatterns = router.urls

You can, of course, also hook URLs up to views the exact same way you connect Django views to URL routes:

from django.urls import path, include

urlpatterns = [
    path('<int:pk>', views.CharacterDetailView.as_view(), name='get_update_delete'),
]

DRF Response and Requests

Much like Django, Django REST Framework, has its own special Response and Request classes. These are based on the Django HttpRequest and TemplateResponse classes respectively, and are redesigned to be easier to use when working with APIs and the nature of API data.

Back to Top