Skip to content

Series Introduction × Target Audience#

2024 iThome Ironman

This is the 1st article in the Django Ninja tutorial series.

In this 30-day series, we will explore the fundamentals of Django Ninja in detail. Through written tutorials and code from an example project, you will become familiar with this powerful and flexible Django API framework step by step.

As a rising star in the Django ecosystem (born in 2020), Django Ninja combines the stability of Django with the modern features of FastAPI—Python type hints (implemented via Pydantic). This powerful combination provides developers with a robust, efficient, and intuitive API development experience.

Whether you are an experienced Django developer or a beginner just entering the field of API development, this series will provide you with practical Django Ninja hands-on experience and tips.

We will start with background introductions and basic concepts, and gradually delve into every part of Django Ninja, helping you quickly master this modern API development tool.

GitHub Example Project#

👉 Django-Ninja-Tutorial

Prerequisites#

This is a beginner-level series—but "beginner" refers specifically to Django Ninja itself.

Therefore, to make the best use of the tutorial content and example project code, it is still recommended that readers possess the following skills:

  • Python Basics: Familiarity with Python syntax, Python development experience is preferred.
  • Django Basics: Understanding the basic components of Django, such as ORM, Views, and MTV architecture. However, there is no need to understand Templates—since we are developing APIs.
  • HTTP and Web API Concepts: Knowing what HTTP, Web API, and front-end/back-end separation are, and having a basic understanding of RESTful API design principles.
  • Version Control: Familiarity with basic Git and GitHub operations so that you can work with the example project.

Possessing these skills will help you better understand and apply the content of this series. If you are not familiar with some concepts, do not worry; we will explain them when necessary.

Target Audience#

This series is particularly well suited to the following readers. See which group sounds most like you.

1. Python Backend Beginners#

Beginners who want to learn Python backend development, especially how to build high-quality APIs.

2. Django Developers#

All Django developers, whether full-stack or backend, are the target audience of this series.

3. FastAPI Developers#

For readers who already have a foundation in FastAPI development, getting started with Django Ninja should be extremely easy 🤚.

4. Developers Looking to Improve API Development Efficiency#

Django Ninja provides a concise and fast way to develop APIs.

One of its biggest selling points is "automatically generating API Documentation through Pydantic and Python Type Hints," saving you from the burden of maintaining high-quality API Documentation by hand.

Automatically Generated API Documentation

For non-Python developers who want to implement small-scale features in small projects, Django Ninja offers a highly attractive choice.

5. Python Developers Who Want to Get Familiar With Type Hints#

I once mentioned in Notes on "Robust Python": How to Effectively Import Type Hints:

To write Django Ninja (or FastAPI), you inherently have to write a lot of type hints to generate correct and reasonable API documentation. Thus, the resistance to adding type hints to the rest of the project, such as custom functions and classes, is relatively much smaller.

In my opinion, using a Pydantic-based framework has the same effect as training wheels on a bicycle—it provides clear, positive guidance when you're just starting out with type hints.

If Python type hints lack practical application scenarios, it often makes people feel that writing these things is hard work and even a bit redundant, which is only human nature.

The best use case is one in which the tool itself requires them and gives you an immediate benefit in return—which is exactly what Django Ninja does.

Directions and Trade-offs#

In this series, we will focus on the core features and practical applications of Django Ninja, aiming to help developers get started quickly and implement APIs.

To keep the content practical and focused, we have made a few trade-offs:

  • Focus on API Development: How to use Django Ninja to define routes, handle requests and responses, etc. These functions are the most common requirements in practical applications and are the parts that beginners should prioritize.
  • Focus on Synchronous Operations: Although Django Ninja supports asynchronous operations (async), Django's support for async is still gradually improving.
  • To avoid confusing beginners with unnecessary technical details, we will only cover synchronous operations.
  • This not only simplifies the development process but also ensures consistency with the current mainstream Django usage habits.
  • Skip Parts Unrelated to API Development: Django, as a batteries-included framework, contains many features beyond the scope of API development, such as internationalization (i18n), template engines, etc.
  • Although these features are important for some application scenarios, they are not highly relevant to the theme of this series, so we choose to skip them.
  • Unit testing, deployment, containerization, and so on will only be touched on briefly rather than covered in full.
  • Special Emphasis on the Creation and Quality of API Documentation: Clear and high-quality API documentation is indispensable in modern software development, especially critical in teamwork or when opening APIs to third parties.
  • Django Ninja has the feature of "automatically generating API documentation from code," and we will delve into how to effectively leverage this feature.
  • What does "delving into" mean? Making sure the API documentation is not just automatically generated, but also highly readable and accurate—so frontend developers can rely on it with confidence.

From Code to Vivid, Easy-to-Read API Documentation

Summary#

Now that you understand the overall direction of the series, I will introduce its structure and chapter organization so that you know what each chapter covers and how the material builds toward Django Ninja's core features.

In the next article, I will explain the theme and focus of each chapter, giving you a clear picture of the entire series and preparing you for what follows.