Building a RESTful API with Django-rest-framework

If you are building APIs with Django and DRF, you should read our API book.
It is updated for Django 2.0+ and Python 3.6+. This book starts where the Django tutorials stop. In the Django tutorials, you built a regular Django polls app. In this book you will build an API for a similar app.
Building APIs with Django and Django Rest Framework

APIs turned to be the heart of every application in our time. With the rise of social media, APIs are being developed at a faster pace and gaining a lot of attention. Gone are the days where RPC architectures like CORBA and XML-RPC are used to enable the exchange of information and REST has taken its place making its mark in getting the things pretty straight forward.

We use APIs in our everyday life. Take an instance booking a ticket for a movie through some website. Here is the process that takes place in the background. When dealing with the payment for the ticket, the website connects to the bank and sends your credit card details to the remote application and it gets verified. And once, the payment is confirmed by the remote application, it sends a confirmation response to the movie booking website to issue the tickets. The payment stuff turned possible here as the bank facilitates an API through which a website can connect to it and deal with the payments which resulted us an effective and seamless transaction.

In this post we will get to know how to build a Restful API for an application using a Django-rest-framework. Before dipping ourselves in the API building stuff, let us acquire a picture on REST.

REST

In simple words REST is a web architecture which lives on top of HTTP. It’s a way in which we should use HTTP where it acts as a set of guiding principles behind the given application. It allows the clients and servers to communicate with each other in all the possible ways like getting the resource, posting the resource, deleting etc. REST is a resource based on which we use an HTTP verb to dictate what operation we want to do on a URI which can be GET, POST and so on. In REST we represent the resource data in JSON and XML format. An API is called a Restful API if it adheres to all the interaction constraints of REST.

Django-rest-framework

Django-rest-framework makes the process of building web API’s simple and flexible. With its batteries included it won’t be a tedious task to create an API. Before creating our own API let us look into some vital parts of the REST framework
The important parts of Django-rest-framework are:

Serialization and Deserialization:
The first part in the process of building an API is to provide a way to serialize and deserialize the instances into representations. Serialization is the process of making a streamable representation of the data which will help in the data transfer over the network. Deserialization is its reverse process. In our process of building an API we render data into JSON format. To achieve this Django-rest-framework provides JSONRenderer and JSONParser.
JSONRenderer renders the request data into JSON, using utf-8 encoding and JSONParser parses the JSON request content.

Without dipping inside the technicalities let us see how it takes place.

Serializing data with JSONRenderer:

A JSONRenderer converts the request data into JSON using utf-8 encoding. Normally we use this when we want our data to be streamable.

A JSONParser parses the JSON request content. Firstly, we parse a stream into Python native datatypes with BytesIO and then we will restore those native datatypes into to a fully populated object instance afterwards. We use JSONParser to desrialize the data.

Requests and responses are the essential parts of Django-rest-framework which provides flexibility while parsing.

Request objects:

The request object in REST framework has more abilities. The attribute request.DATA in Request object is similar to Request.POST added with the capabilities of handling arbitrary data which works for ‘POST’, ‘PUT’ and ‘PATCH’ methods. And also we can use the different attributes like request.FILES, request.QUERY_PARAMS, request.parsers, request.stream which will help in dealing with the request a hassle free task.

Response objects:

The Response object helps to render the correct content type as requested by the client unlike the normal HttpResponse.

Status Codes:
Instead of using the normal HTTP status codes, we will make use of explicit identifiers for every status code to make the process of reading the status code much simple. Here are some status codes that we represent in a REST framework we use normally.

Views:
APIView is a view provided by Django-rest-framework which subclasses the Django’s view class. If we use this view the requests passed to the handler methods will no more Django’s HttpRequest instances and they will be REST framework’s Request instances.
And while dealing with the responses they work to set the correct renderer on the response. The process of authentication and the permissions stuff also will be dealt with it.

Creating an API with Django-rest-framework

Using all the above stuff lets us build a simple API which gives the details of a user. The procedure goes the following way:

We will be using Django’s built in user in this example. We will create a serializers.py file where we create serializers which are similar to Django forms. Just like model forms we have got model serializers here, which will stop replication of code. And we create a view which lists all the users, creates a new user, retrieve a user and update a user.

Here we go with the installation with virtual environment activated:

pip install djangorestframework

Create a Django project and an app. I created it with a name rest_example and restapp