How to Create More Understandable APIs in Python

This blog explores how you can create APIs in Python using Django, Django Rest Framework (DRF), and drf-yasg. We’ll explain what each of these frameworks provides, and detail an example so you can see how you might use them in your own projects.

 

Why Create APIs in Python?

Python is a high-level, general-purpose programming language. Most developers find Python to be very easy to use and very flexible. 

A major hallmark of Python is its readability. Developers need not worry about syntax and can focus more on the code itself. For example, while many programming languages use syntax like semicolons and parentheses to show when a command completes, Python uses a new line. While many programming languages use brackets or parentheses to show the scope of a function, a class or a loop, Python uses indentations.

Python also supports both procedure-oriented and object-oriented programming. 

Regardless of whether you’re working with Python 2 or Python 3 (we won’t get into the differences in this blog), Python’s strength and versatility make it a natural choice for a wide variety of projects, including:

• web development (server-side)

• mathematics

• system scripting

 

What is Django?

Django is an easy-to-use Python framework that lets you create powerful, robust, and high-performance APIs for web applications. 

Django includes a default object-relational mapping layer (ORM) that can interact with application data from various relational databases such as SQLite (the default), MySQL, PostgreSQL, SQL Server, and more. This means you don’t have to tackle SQL explicitly on Python. You can just use Python instructions to access the database which makes it more secure. 

 

What is Django DRF?

You can extend Django functionalities to create more powerful REST APIs by adding Django REST framework (DRF) to your Django project. With DRF, you gain powerful, new functionality, including:

• serializers (to convert HTTP data to Python) 

• models (to convert Database instructions to Python)

• decorators (to modify or extend functions)

• responses (you can customize HTTP responses) 

 

What is drf-yasg?

By default, DRF has an API view that works very well, but the UI provides only a limited way to see endpoints and isn’t very clear. To gain this capability, you can use drf-yasg, a Swagger generation tool and library available for Django. Using drf-yasg, you can create APIs in a more organized and user-friendly way than is possible with the default structures provided by Django. drf-yasg provides many benefits including: 

• Easy to learn.

• Adds a variety of features to the Swagger UI views.

• Completely configurable using the default Django settings file.

• Easy to integrate with Django models.

• Easy to integrate with the rest of Python code, such as functions, decorators, and more.

The main features of drf-yasg include support for:

• Nested serializers and schemas

• Response schemas and descriptions

• Model definitions compatible with codegen tools

• JSON and YAML formats for specs

• Django REST Framework API versioning

Note: As of the writing of this blog, Django Rest Swagger does not seem to be maintained and may soon be deprecated. If you’re considering whether to use Django Rest Swagger or drf-yasg, you should keep this in mind and plan accordingly. 

 

Set up the Environment for drf-yasg

The first step to create APIs in Python is to set up the environment to explore how to use drf-yasg: 

1. Install the drf_yasg library (include it as part of the requirements.txt file).

2. Create an application inside your Django project.

3. Define the project urls and the application urls; then link them by using the “include” component from django urls.

4. Use Django routers to manage your application urls.

5. Create the schema that Swagger will use to show your views and to define the desired attributes to the openapi.info component.

6. Go to your desired view and add the details you want the endpoint to have, by using the @swagger_auto_schema decorator from drf_yasg.utils.

 

Now Let’s See drf-yasg in Action

1. Open drf-yasg in a browser and you see that this is how a basic API appears:

For this blog, I created an API called CR Register, which has only one endpoint, called person-data.

2. Click that endpoint and it will expand to show you the details, as we show here:

3. In this window, you can add parameters and response examples to the endpoint. 

You use decorators and strings to define the parameters and responses respectively, as shown in this screenshot below:

 

Discover the Many Benefits of Using drf-yasg 

Using drf-yasg is easy and you can start using it with no advanced knowledge of Python and Django. If you take the time to learn it, you gain many benefits:

• You can extend the components we configured in this blog to make your own APIs more understandable, beautiful and self-documented for other developers.  

• You get a customizable API that fully integrates with Python and DRF while gaining all the advantages that these frameworks have. 

• You can create APIs in Python that are more powerful, beautiful, and efficient. 

• You’ll stay current in one of the most recent and most popular libraries for Swagger APIs, and you’ll be more competitive in your industry.