Tag: REST API

Python

Django REST Framework: Serializers

Post author By masnun
Post date May 13, 2017

(This post is a part of a tutorial series on Building REST APIs in Django)

In our last blog post, Getting started with Django REST Framework, we saw how we could use the APIView and accept inputs from users using request.data. In our example, we dealt with string, so it was pretty straightforward. But consider the case of age or account_balance – one has to be integer, the other has to be float / decimal. How do we properly validate the incoming data?

We can manually check every input field and send an error if the field type doesn’t match. But soon we’re going to have a problem at our hand – when the number of inputs will grow, we can’t just keep doing this kind of manual validation. In Django, we would probably use Django Forms for validation. Does DRF provide us with something similar? Yes, it does. The solution to our problem is Serializers.

What can a Serializer do for us?

Have you ever tried JSON serializing a Django model? Or a queryset? You can’t directly because they are not JSON serializable. So what do we do instead? We convert them to Python’s native data structures which could be serialized into JSON. We can serialize querysets into lists and model instances to dictionaries. But doing that by hand is cumbersome.

On the other hand, we saw how we can get incoming data from request.data – we get this data as key value pairs. We can’t just store them in database directly – we have to transform them into Django’s data structures like models and querysets. Doing that by hand is also cumbersome.

Serializers can help us with that. It can serialize complex types into Python natives types and then again deserialize native types into those complex types. Besides that, it also does basic validation based on the serializer field types. If a field is defined as an integer field, it will raise an error if we pass a string to that field. If we need more advanced validation rules, we can plug in the built in Validators or even write our own. Let’s see code examples to understand the use case better.

Defining a Serializer

Create a file named serializers.py inside the api app directory. Put the following codes into it.

from rest_framework import serializers


class HelloWorldSerializer(serializers.Serializer):
    name = serializers.CharField(required=True, max_length=6)
    age = serializers.IntegerField(required=False, min_value=10, default=10)

from rest_framework import serializers

class HelloWorldSerializer(serializers.Serializer):

name = serializers.CharField(required=True, max_length=6)

age = serializers.IntegerField(required=False, min_value=10, default=10)

We’re creating a HelloWorldSerializer which extends serializers.Serializer. We’re defining two fields on this serializer –

name is a CharField so it accepts string. It has a max_length of 6.
age is an optional integer field. The value must be at least 10 if provided. If not provided, default value will be 10.

With this serializer setup, let’s modify our view to use it.

from .serializers import HelloWorldSerializer


class HelloWorldView(APIView):
    def get(self, request):
        return Response({"message": "Hello World!"})

    def post(self, request):
        serializer = HelloWorldSerializer(data=request.data)
        if serializer.is_valid():
            valid_data = serializer.data

            name = valid_data.get("name")
            age = valid_data.get("age")

            return Response({"message": "Hello {}, you're {} years old".format(name, age)})
        else:
            return Response({"errors": serializer.errors})

from .serializers import HelloWorldSerializer

class HelloWorldView(APIView):

def get(self, request):

return Response({"message": "Hello World!"})

def post(self, request):

serializer = HelloWorldSerializer(data=request.data)

if serializer.is_valid():

valid_data = serializer.data

name = valid_data.get("name")

age = valid_data.get("age")

return Response({"message": "Hello {}, you're {} years old".format(name, age)})

else:

return Response({"errors": serializer.errors})

We pass the request.data as the data parameter to HelloWorldSerializer so it can read all the request data and parse them. Then we check if the serializer is valid. If you have used Django Forms, this will feel very similar. If the serializer is valid, that means we have a valid set of data available. So we can take the value of name and age and show a pretty message. On the other hand, if the serializer is not valid, we can pass the serializer.errors back to the client, which will contain elaborate error messages.

Let’s try out the API to see what happens. Let’s first send an empty request:

$ curl -H "Content-Type: application/json" -X POST http://localhost:8000/api/hello

{"errors":{"name":["This field is required."]}}

$ curl -H "Content-Type: application/json" -X POST http://localhost:8000/api/hello

{"errors":{"name":["This field is required."]}}

The errors say the name field is required. Of course it is! Let’s pass the name.

$ curl -H "Content-Type: application/json" -X POST -d '{"name": "masnun"}' http://localhost:8000/api/hello

{"message":"Hello masnun, you're 10 years old"}

$ curl -H "Content-Type: application/json" -X POST -d '{"name": "masnun"}' http://localhost:8000/api/hello

{"message":"Hello masnun, you're 10 years old"}

We just passed the name but didn’t pass the age. Since it is not required and has a default value set, we get the default value. But what if we set a low value?

$ curl -H "Content-Type: application/json" -X POST -d '{"name": "masnun", "age": '8'}' http://localhost:8000/api/hello

{"errors":{"age":["Ensure this value is greater than or equal to 10."]}}

$ curl -H "Content-Type: application/json" -X POST -d '{"name": "masnun", "age": '8'}' http://localhost:8000/api/hello

{"errors":{"age":["Ensure this value is greater than or equal to 10."]}}

So we passed 8 and it’s not happy about that. Please note we passed the 8 as a string but DRF doesn’t mind as long as it can convert it to an integer successfully. What if we pass a value that is no number?

$ curl -H "Content-Type: application/json" -X POST -d '{"name": "masnun", "age": "ten"}' http://localhost:8000/api/hello

{"errors":{"age":["A valid integer is required."]}}

$ curl -H "Content-Type: application/json" -X POST -d '{"name": "masnun", "age": "ten"}' http://localhost:8000/api/hello

{"errors":{"age":["A valid integer is required."]}}

That works too! Cool, okay then let’s give it a rest and pass a valid value.

$ curl -H "Content-Type: application/json" -X POST -d '{"name": "masnun", "age": 12}' http://localhost:8000/api/hello

{"message":"Hello masnun, you're 12 years old"}

$ curl -H "Content-Type: application/json" -X POST -d '{"name": "masnun", "age": 12}' http://localhost:8000/api/hello

{"message":"Hello masnun, you're 12 years old"}

Serializer with Model

How does Serializers help us in working with models? To understand that, let’s first create one model.

Creating the Subscriber Model

Open api/models.py and add the Subscriber model like this:

class Subscriber(models.Model):
    name = models.CharField("Name", max_length=50)
    age = models.IntegerField("Age")
    email = models.EmailField("Email")

class Subscriber(models.Model):

name = models.CharField("Name", max_length=50)

age = models.IntegerField("Age")

email = models.EmailField("Email")

Now create and run the migration.

python manage.py makemigrations
python manage.py migrate

1 2	python manage.py makemigrations python manage.py migrate

That should setup the table for our new model.

Update The Serializer

We added an email field to our model, also the max length for name is now 50 chars. Let’s update our serializer to match these constraints. Also rename it as SubscriberSerializer.

from rest_framework import serializers


class SubscriberSerializer(serializers.Serializer):
    name = serializers.CharField(max_length=50)
    age = serializers.IntegerField()
    email = serializers.EmailField()

from rest_framework import serializers

class SubscriberSerializer(serializers.Serializer):

name = serializers.CharField(max_length=50)

age = serializers.IntegerField()

email = serializers.EmailField()

Update The View

And now let’s refactor our view.

from .serializers import SubscriberSerializer
from .models import Subscriber


class SubscriberView(APIView):
    def get(self, request):
        return Response({"message": "Hello World!"})

    def post(self, request):
        serializer = SubscriberSerializer(data=request.data)
        if serializer.is_valid():
            subscriber_instance = Subscriber.objects.create(**serializer.data)
            return Response({"message": "Created subscriber {}".format(subscriber_instance.id)})
        else:
            return Response({"errors": serializer.errors})

from .serializers import SubscriberSerializer

from .models import Subscriber

class SubscriberView(APIView):

def get(self, request):

return Response({"message": "Hello World!"})

def post(self, request):

serializer = SubscriberSerializer(data=request.data)

if serializer.is_valid():

subscriber_instance = Subscriber.objects.create(**serializer.data)

return Response({"message": "Created subscriber {}".format(subscriber_instance.id)})

else:

return Response({"errors": serializer.errors})

The code is very simple and straightforward. If the serializer validation succeeds, we create a new subscriber out of the validated data.

Update URLConf

Let’s update the urls.py to update our url end point.

url(r'^subscriber', SubscriberView.as_view(), name="subscriber")

1	url(r'^subscriber', SubscriberView.as_view(), name="subscriber")

Now let’s try it out. We will post the following JSON using curl or postman:

{"name": "Abu Ashraf Masnun", "email": "masnun@polyglot.ninja", "age": 29}

1	{"name": "Abu Ashraf Masnun", "email": "masnun@polyglot.ninja", "age": 29}

And we will get back the following response:

{
  "message": "Created subscriber 1"
}

{

"message": "Created subscriber 1"

}

With the serializer, we needed so much less codes. And we did it in a very clean way.

List All Subscribers

According to the REST Best Practices, the GET call to a resource route (/api/subscriber) should return a list of all the items (subscribers). So let’s refactor the get method to return the subscribers list.

    def get(self, request):
        all_subscribers = Subscriber.objects.all()
        serialized_subscribers = SubscriberSerializer(all_subscribers, many=True)
        return Response(serialized_subscribers.data)

def get(self, request):

all_subscribers = Subscriber.objects.all()

serialized_subscribers = SubscriberSerializer(all_subscribers, many=True)

return Response(serialized_subscribers.data)

We are fetching all subscribers and then passing the queryset to the serializer constructor. Since we’re passing a query set (not just a single model instance rather a list of model instances), we need to set many=True . Also note, we don’t need to call is_valid – the data is coming from database, they’re already valid. In fact, we can’t call is_valid unless we’re passing some value to the data parameter (SubscriberSerializer(data=request.data)). When we pass queryset or model, the data is automatically available as serializer.data.

What’s Next?

We have so far learned how to use APIView and Serializer to build beautiful APIs with clean code. But we still have some duplication of efforts, for example when we had to define fields on both the model and the serializer. Also, we have to implement both collection and element resources. So that’s like 5 method implementation. Wouldn’t it be great if, by some mechanism we could make things simpler, shorter and cleaner?

We’ll see, in our next blog post 🙂 Please subscribe to our mailing list for email updates. Also if you liked the content, please don’t forget to share with your friends!

Tags Django, Django REST Framework, REST API

Python

Django REST Framework: Getting Started

Post author By masnun
Post date May 13, 2017

(This post is a part of a tutorial series on Building REST APIs in Django)

In our last post about Building APIs in Django, we explained why using Django REST Framework would be a good idea. In this post, we will start writing our APIs using this awesome framework. DRF itself works on top of Django and provides many useful functionality that can help with rapid API development.

Installing Django REST Framework

We have to install DRF first. We can install it using pip as usual.

pip install djangorestframework

1	pip install djangorestframework

Once the installation succeeds, add rest_framework to the INSTALLED_APPS list in settings.py.

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    

    'rest_framework',
    
    'api'
]

INSTALLED_APPS = [

'django.contrib.admin',

'django.contrib.auth',

'django.contrib.contenttypes',

'django.contrib.sessions',

'django.contrib.messages',

'django.contrib.staticfiles',

'rest_framework',

'api'

]

Now we are ready to start building our awesome APIs!

Using APIView

APIView class is quite similar to Django’s View class except it is more REST-y! The APIView class can be considered as quite similar to the Flask Resource class from our Flask Tutorial. An APIView has methods for the HTTP verbs. We can implement our own methods to handle those requests the way we want.

Let’s modify the function we wrote in our first post to use APIView instead.

from rest_framework.views import APIView
from rest_framework.response import Response


class HelloWorldView(APIView):
    def get(self, request):
        return Response({"message": "Hello World!"})

from rest_framework.views import APIView

from rest_framework.response import Response

class HelloWorldView(APIView):

def get(self, request):

return Response({"message": "Hello World!"})

We have done two things –

Our HelloWorldView extends APIView and overrides the get method. So now DRF knows how to handle a GET request to the API.
We return an instance of the Response class. DRF will do the content negotiation for us and it will render the response in the correct format. We don’t have to worry about rendering JSON / XML any more.

Since we are now using a class based view, let’s update the urlconf and make the following change:

url(r'^hello', HelloWorldView.as_view(), name="hello_world")

1	url(r'^hello', HelloWorldView.as_view(), name="hello_world")

That’s all the change that is necessary – we import the class based view and call the as_view method on it to return a view that Django can deal with. Under the hood, the as_view class method works as an entry point for the request. The class inspects the request and properly dispatches to the get, post, put etc methods to process the request. It then takes the result and sends back like a normal function based view would do. In short, the as_view method kind of works as a bridge between the class based view and the function based views commonly used with Django.

The Web Browsable API

If you visit http://localhost:8000/api/hello you will now see a nice html view with our json response displayed along with other useful information (response headers). This html view is an excellent feature of DRF – it’s called the web browsable API. The APIs we create, DRF automagically generates a web view for us from where we can interact with our API, testing / debugging things. No need for swagger or any other external clients for testing. Awesome, no?

Function Based APIView

We can also use a function based form of APIView where we write a function and wrap it using the api_view decorator. An example would look like this:

from rest_framework.response import Response
from rest_framework.decorators import api_view


@api_view(["GET", "POST"])
def hello_world(request):
    if request.method == "GET":
        return Response({"message": "Hello World!"})

    else:
        name = request.data.get("name")
        if not name:
            return Response({"error": "No name passed"})
        return Response({"message": "Hello {}!".format(name)})

from rest_framework.response import Response

from rest_framework.decorators import api_view

@api_view(["GET", "POST"])

def hello_world(request):

if request.method == "GET":

return Response({"message": "Hello World!"})

else:

name = request.data.get("name")

if not name:

return Response({"error": "No name passed"})

return Response({"message": "Hello {}!".format(name)})

And in the urls.py, the entry will look like this:

url(r'^hello', hello_world, name="hello_world")

1	url(r'^hello', hello_world, name="hello_world")

I mostly use function based views when things are really simple and I have to handle just one type of request (say, POST or GET). But in case I have to handle multiple type of requests, I will then have to check request.method to determine the type and handle accordingly. I find the class based view cleaner and well organized than writing a bunch of if else blocks.

You can read more about the function based APIView in the docs.

Accepting Input

We have seen how to write a simple end point to say “hello world!” – that is great. But now we must learn how we can handle inputs from our user. For this demonstration, on our /api/hello endpoint, we would accept a name in a POST request. If the name is passed, we will show a customized greeting. Let’s get to work!

class HelloWorldView(APIView):
    def get(self, request):
        return Response({"message": "Hello World!"})

    def post(self, request):
        name = request.data.get("name")
        if not name:
            return Response({"error": "No name passed"})
        return Response({"message": "Hello {}!".format(name)})

class HelloWorldView(APIView):

def get(self, request):

return Response({"message": "Hello World!"})

def post(self, request):

name = request.data.get("name")

if not name:

return Response({"error": "No name passed"})

return Response({"message": "Hello {}!".format(name)})

We have added a post method that should handle the POST requests. Instead of request.POST, we would use request.data which works across POST, PUT, PATCH – all other methods too. If the name is not passed we send error message. Otherwise we send a hello world message.

With that code written, let’s try it out –

$ curl -H "Content-Type: application/json" -X POST -d '{"name":"masnun"}' http://localhost:8000/api/hello

{"message":"Hello masnun!"}

$ curl -H "Content-Type: application/json" -X POST -d '{"name":"masnun"}' http://localhost:8000/api/hello

{"message":"Hello masnun!"}

Aha, things worked as expected! Cool! What if we don’t pass the name?

$ curl -H "Content-Type: application/json" -X POST  http://localhost:8000/api/hello

{"error":"No name passed"}

$ curl -H "Content-Type: application/json" -X POST http://localhost:8000/api/hello

{"error":"No name passed"}

It works exactly like we wanted it to! Fantastic!

What’s next?

In this post, we saw how the APIView works and how we can accept inputs and send responses for different http verbs. In the next post, we will discuss about serializers and how they can be useful.

If you would like to get notified when we post new content, please subscribe to our mailing list. We will email you when there’s something new here 🙂

Tags Django, Django REST Framework, REST API

Python

Django: Building REST APIs

Post author By masnun
Post date May 13, 2017
16 Comments on Django: Building REST APIs

Recently, I have written a few pieces on REST API development. We have discussed the Fundamentals of REST APIs, Built a Simple REST API, Secured it with HTTP Basic Authentication and JSON Web Tokens. However, the example codes were all based on Flask. I chose Flask for those examples because the framework was minimal in it’s core, light weight yet popular and with a matured eco system – very well suited for demonstrating simple REST APIs. But if we consider popularity, probably no other framework is as popular as Django in the Python land. In my day to day work, I use the framework quite extensively. Over the years, I have grown to become a passionate fan of Django. Naturally a tutorial series on building REST APIs with Django was just a matter of time.

Tutorial Index

This is the first part of the series. I shall update the index here as I keep adding new contents.

Getting Started (This post)
Getting Started with Django REST Framework
Serializers
ModelSerializer and Generic Views
ViewSet, ModelViewSet and Router
Authentication and Permissions
Using JWT

Code: https://github.com/masnun/djmailer

Prerequisites

The tutorial series will be heavily focused on building REST APIs. So there will be less scope of discussing the fundamentals of Django as we go. I would expect the reader to have decent familiarity of Django before hand. If you are new to Django, please spend some time with the Official Tutorial. It is very well written.

The tutorial series will use Python 3.6.0 (but any versions above Python 3.0 should work fine). As for Django, I have just installed the latest release as of today – 1.11. . We would also be using Django REST Framework, I have 3.6.3 right now. The example code repository will have an up-to-date requirements.txt file – so don’t worry much about dependencies or their versions right now. Just make sure you use Python 3 and not Python 2.

Setting Up Django

Before we can start working on our awesome REST API, we first need to setup and configure our Django project. We need to install Django, install dependencies, start a project and an app, configure the database connection and write our first view. So what are we waiting for? Let’s get started!

Install Django and Dependencies

For now, we need the latest Django and a database driver. We will be using MySQL since it’s very popular and most people are familiar with it. In our production systems though, we mostly run PostgreSQL. We will discuss that choice in some later posts. Let’s install Django and the MySQL client using pip.

pip install django
pip install mysqlclient

1 2	pip install django pip install mysqlclient

Done? Cool. If Django installed successfully, you should be able to run the django-admin.py command. See if you can run it. If the command runs successfully, your installation worked. Time to move on to the next phase.

Create the Django Project

We want to build REST APIs for a mailing list. Let’s call it djmailer. We use the startproject admin command to start our project.

django-admin startproject djmailer

1	django-admin startproject djmailer

We would now have a directory named djmailer created in the current directory. Within that, there’s the default djmailer app directory which contains the settings and root urlconf and the uwsgi app.

Create a New App

For the API related stuff, we would now create a new app named api. Let’s do that. First cd into the project so you can access the manage.py file. Now run this command:

python manage.py startapp api

1	python manage.py startapp api

Cool, now we have the api app created for us. Open up djmailer/settings.py and add api to the INSTALLED_APPS list.

Configure Database

In the default djmailer app, there’s a file named settings.py. Open it up in your favorite text editor. We need to add our database credentials here. We will notice that a sample database configuration is already generated for us. Something like:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
    }
}

DATABASES = {

'default': {

'ENGINE': 'django.db.backends.sqlite3',

'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),

}

The above example uses SQLite. But we want to use MySQL. So first create a database named djmailer on your MySQL server and create the database user and password. Then replace the above code with these lines:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'djmailer',
        'USER': 'djmailer',
        'PASSWORD': 'suP3rS3CR3t!X$%^',
    }
}

DATABASES = {

'default': {

'ENGINE': 'django.db.backends.mysql',

'NAME': 'djmailer',

'USER': 'djmailer',

'PASSWORD': 'suP3rS3CR3t!X$%^',

}

Once you have configured the database, please run the migrate management command.

python manage.py migrate

1	python manage.py migrate

This should create the tables Django needs for itself.

Hello World!

Time to create our first view. Open api/views.py file and create the view:

from django.http.response import JsonResponse


def hello_world(request):
    return JsonResponse({"message": "hello world!"})

from django.http.response import JsonResponse

def hello_world(request):

return JsonResponse({"message": "hello world!"})

Instead of the usual HttpResponse, we used JsonResponse because we want to render our response as JSON. Using this class ensures that the reponse is JSON and the appropriate content type is set.

We can add this view directly to the root urlconf in djmailer/urls.py but we would like to better organize our urls. So we are going to create a new file named urls.py in the api directory and put the following content:

from django.conf.urls import url

from .views import hello_world

urlpatterns = [
    url(r'^hello', hello_world, name="hello_world")
]

from django.conf.urls import url

from .views import hello_world

urlpatterns = [

url(r'^hello', hello_world, name="hello_world")

]

If we add urls from all apps to the root urlconf, it will soon become a mess. Also the apps will not be reusable. But if we keep our app specific routes inside the app, we can just import them from the root urlconf. This keeps things clean and the app can be easily plugged into a different project if needed.

Let’s edit djmailer/urls.py (the root urlconf) and import our api urls.

from django.conf.urls import url, include
from django.contrib import admin

from api import urls as api_urls

urlpatterns = [
    url(r'^api/', include(api_urls, namespace="api")),
    url(r'^admin/', admin.site.urls),
]

from django.conf.urls import url, include

from django.contrib import admin

from api import urls as api_urls

urlpatterns = [

url(r'^api/', include(api_urls, namespace="api")),

url(r'^admin/', admin.site.urls),

]

Focus on line 4 and 7. We are importing our api urls and putting them under the /api/ path. Run the django dev server:

python manage.py runserver

1	python manage.py runserver

If we visit http://localhost:8000/api/hello, we would see the response:

{"message": "hello world!"}

1	{"message": "hello world!"}

Cool? We just built our first RESTful view with Django.

Introducing Django REST Framework (DRF)

Building REST APIs with plain old Django is very possible but we have to do a lot. We need to read incoming requests, parse them as JSON or XML (through content negotiation), in case of CRUD operations, we also have to work with models and finally we have to send back the response in appropriate format. It’s all possible in Django – but like I said, I have to do so many things on our own. Our initial hello world view was very basic, very simple. As the project grows and we have more and more complexities, things will start to get out of hands.

In our Flask examples, using a third party extension helped us get started faster and saved us much time and efforts. Django REST Framework is one such framework for Django. It provides so much functionality out of the box – I am a big fan of the framework. So while we can do everything without this framework, using it would make us productive and keep things sane.

So from now on, we would be using DRF to continue building our APIs. In the next blog post, we would be getting started with Django REST Framework.

What’s Next?

On our next post – Django REST Framework: Getting Started, we introduce you to the wonderful world of DRF and demonstrate how we can use APIView to build our endpoints.

In the mean time, please subscribe to our mailing list. We will keep you posted when we publish new content. 🙂

Tags Django, Django REST Framework, REST API

Recent Posts

Recent Comments

Archives

Categories