DEV Community

Wulfi
Wulfi

Posted on

A Step-By-Step Guide to Building an API in Django

This tutorial will teach you how to set up a Django project and create an API that will return the anime list.

API is a middle man between two apps. It allows one app to use the features of another app. For example, an API can be used to allow a social media platform to access a user’s location data from their phone.

APIs are used to connect different pieces of software and allow them to communicate with one another. They can also be used to make a piece of software interact with something else, like a database or web page. In general, project A and project B can be connected through an API .

An API can be used to create projects in different domains. For example, an API can be used by an online retailer to give them access to customer data from their website.

The definition of An application programming interface ( API) by Wikipedia is a connection between computers or between computer programs. It is a type of software interface, offering a service to other pieces of software.

When interacting with the API, we send requests and get responses. The request are of different types:

C — create (POST)
R — Read (GET)
U — Update (PUT)
D — Delete(DELETE)
Enter fullscreen mode Exit fullscreen mode

In this tutorial, we will create an API that will return a simple JSON response and I will write a separate article on creating each of the above methods.

1. Setup Django Project

Django is a Python web framework that is designed for rapid development of high-quality web applications. It is free and open source software under the BSD license.

Django’s primary distinguishing features are its “batteries included” approach to web development, which includes many things that are typically hard or time consuming to build from scratch such as user authentication, database access, caching support and more; its emphasis on readability; and its use of Python as an implementation language. You may learn Django from its documentation here

For now we only need Django and a code editor (I’m using Vscode) to work on this project.

i. Create a folder to work on this project.

ii. Inside the folder you just created, create a virtual environment. To create a virtual environment, open the terminal inside this folder and enter:


$ python -m venv env
Enter fullscreen mode Exit fullscreen mode

iii. Activate the virtual environment and install Django

$ env\Scripts\activate$ pip install Django
Enter fullscreen mode Exit fullscreen mode

iv. Create the project :

Since we are creating an anime list API, we will create a project called animelist:

$ django-admin startproject animelist $ cd animelist
Enter fullscreen mode Exit fullscreen mode

ii. Create app inside our project

Generally if we need to add any feature or if we need to do anything in Django, we need to create apps. So complete projects are divided into multiple apps. Let us create our first app using following command:

$ python manage.py startapp animelist_app
Enter fullscreen mode Exit fullscreen mode

Add the app inside 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',
    'animelist_app',
]

Enter fullscreen mode Exit fullscreen mode

We will test our project to see if we can see the default page of Django project:

$ python manage.py runserver
Enter fullscreen mode Exit fullscreen mode

2. Create Django Models

Creating models in Django is an important step for any developer. It’s the first step of creating a database in Django and it’s also the first step for creating a web application.

Django models are classes that represent database tables. They are used to create, read, update and delete data from the tables.

In this tutorial, we will create one API model for an anime list.

i. When the Django project is first created, several migrations need to be performed. We can do this by running following command:

$ python manage.py migrate

Enter fullscreen mode Exit fullscreen mode

ii. Create superuser by providing the details when running the following command:

$ python manage.py createsuperuser
Enter fullscreen mode Exit fullscreen mode

Now, try accessing the Django admin interface by running the server:

$ python manage.py runserver
Enter fullscreen mode Exit fullscreen mode

Visit: 127.0.0.1:8000/admin

iii. Create urls.py file inside the animelist_app folder:

Django follows something called MVT architecture which are model (database), view, templates and the urls in Django will tell us which endpoints to hit to get the information or it specifies the paths inside the project.

urls.py

iv. Create a model inside the models.py file. In the following code, we want to create a database table called Anime:

class Anime(models.Model):
    name = models.CharField(max_length=50)
    description = models.CharField(max_length=200)
    active = models.BooleanField(default=True)


    def __str__(self):
        return self.name
Enter fullscreen mode Exit fullscreen mode

v. Since we have added to our model we need to make migrations:

$ python manage.py makemigrations
Enter fullscreen mode Exit fullscreen mode

One of the amazing features in Django is that it supports ORM (Object-Relational Mapper) which enables us to interact with our databases like we would with SQL queries. The fact that it is just a pythonical way of creating SQL queries, manipulating databases and getting results, it is easier that the developer need not write any SQL since ORM automates this work. Run the following command to create the database.

$ python manage.py migrate
Enter fullscreen mode Exit fullscreen mode

vi. Register the model in admin.py

from animelist_app.models import Anime

admin.site.register(Anime)
Enter fullscreen mode Exit fullscreen mode

Run the server and try to add some animes to the database from the admin interface at

127.0.0.1:8000/admin

3. Creating JSON response

i. Here we convert the query set (objects) of Django models into python dictionary and then into JSON

from animelist_app.models import Anime
from django.http import JsonResponse

def anime_list(request):
    animes= Anime.objects.all()

    # print(list(animes.values()))

    data = {
        'animes': list(animes.values())    
    }

    return JsonResponse(data)
Enter fullscreen mode Exit fullscreen mode

This will return the JsonResponse … we can check if it is in JSON by checking if the data is in double quotes (single quotes are changed to double in JSON), capital T for True in the dictionary is changed to small t in JSON.

2/ Create a link for the view above in urls.py

urls.py inside animelist:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('anime/', include('animelist_app.urls')),
]

Enter fullscreen mode Exit fullscreen mode

urls.py inside animelist_app:

from django.urls import path
from animelist_app.views import anime_list

urlpatterns = [
    path('list/', anime_list, name = 'anime-list'),
]

Enter fullscreen mode Exit fullscreen mode

Check the results at 127.0.0.1:8000/anime/list

4. Create view for single data

i. Create a view to return single element or details of single anime

# return individual elements
def anime_details(request, pk):
    anime= Anime.objects.get(pk=pk)

    data = {
        'name': anime.name,
        'description': anime.description,
        'active': anime.active
    }

    # print(anime.name)

    return JsonResponse(data) # convert to json
Enter fullscreen mode Exit fullscreen mode

ii. Add url inside the urls.py file of animelist_app :

from animelist_app.views import anime_list, anime_details

urlpatterns = [
    path('list/', anime_list, name = 'anime-list'),
    path('<int:pk>', anime_details, name='anime-detail'),
]
Enter fullscreen mode Exit fullscreen mode

Test the API by visiting: 127.0.0.1:8000/anime/1

Until now we have created a JSON response by converting the python dictionary data from our model JSON. This is going to be a lot of work when we have a large number of objects to be converted, during that time we might choose to use the Django rest framework where we can convert to JSON with something called serializations.

5. Testing API Endpoints Using Postman

API testing is essential to the development process. Postman is a great tool for API testing. It can be used to generate and test API endpoints. You can also use it to test your API by generating and sending different requests, as well as checking the responses for errors and other potential problems.

If you don’t have Postman, you may download it from here

Since we have only two endpoints to test our API, select the GET method from the left and paste the endpoint as follows. Click on send to check the response

First endpoint: Get animelist response
Image description

Second endpoint: Get single anime detail
Image description

Conclusion:

In this tutorial, we went over the process of building an anime list API with Django.

Oldest comments (5)

Collapse
 
user64bit profile image
Arth

Great Post 👍👍
Thanks for sharing such post ✌✌
So I was thinking,
Which is the best platform to deploy this api?

Collapse
 
wulfi profile image
Wulfi

I've only deployed such simple apis on heroku which is also for free, I'm not really sure which platform would be a best for deployment.. but my experience on heroku is that it is easy do deploy on heroku.. only problem I had was slow data loading and I cannot store images since I use free account. Overall, it's great for me

Collapse
 
user64bit profile image
Arth

It would be great post about how to deploy api on heroku for free?
Thanks for your response ✌✌

Thread Thread
 
wulfi profile image
Wulfi

medium.com/@wdzz/how-to-deploy-dja...

I've written on how to deploy the Django app on Heroku for free, I followed those steps to deploy my API too ... Thank you for the suggestion🙂, I'll try to write on it too

Collapse
 
andrewbaisden profile image
Andrew Baisden

Nicely done! Python is such a versatile programming language.