# Chapter 1

### Introduction to Django Ninja

Building APIs the Easy Way

### What Is Django Ninja?

Django Ninja is a tool that helps you build APIs (Application Programming Interfaces) using\
Python and Django — but faster, cleaner, and with less code.

It’s called **“Ninja”** because it’s:

* **Fast** – built on top of FastAPI ideas
* **Simple** – you write fewer lines of code
* **Smart** – it checks your data automatically

So instead of writing a lot of code to make a simple API, Django Ninja does most of the\
heavy lifting for you.

### Why Should You Learn Django Ninja?

Because it makes API development easy — especially if you are a beginner in backend\
development or Django.

Here’s what makes it special:

| Feature        | Django Ninja         | Django REST Framework (DRF) |
| -------------- | -------------------- | --------------------------- |
| Speed          | Very fast (ASGI)     | Slower (WSGI)               |
| Code size      | Less code            | More boilerplate            |
| Validation     | Automatic (Pydantic) | Manual setup                |
| Docs           | Auto Swagger & ReDoc | Optional setup              |
| Learning curve | Beginner-friendly    | Steeper                     |

### What Django Ninja Does for You

When you create an API, Django Ninja:

* Takes incoming data (from web or mobile apps)
* Validates it automatically
* Passes it to your function to process
* Returns a clean JSON response
* Generates interactive API documentation automatically

All that — from just a few lines of code!

### Example: Your First Django Ninja API

Here’s how easy it is to make your first API with Django Ninja:

```python
# api.py
from ninja import NinjaAPI

api = NinjaAPI()

@api.get("/hello")
def say_hello(request):
    return {"message": "Hello, Django Ninja!"}
```

### Let’s Understand What’s Happening

* `NinjaAPI()` → Your main API application
* `@api.get("/hello")` → Creates an endpoint at `/hello`
* `say_hello()` → Runs when someone visits `/hello`
* Returning a dictionary → Automatically converted to JSON

Now run your Django project and open:

```
http://127.0.0.1:8000/api/docs
```

You’ll see a Swagger documentation page where you can test your `/hello` endpoint — no setup needed.

### The “API Docs” Magic

The `/api/docs` page is a live testing playground that Django Ninja builds automatically.

It shows:

* Every endpoint in your project
* Required inputs
* Expected outputs
* A **Try it out** button to test directly
* Saves hours of manual testing

### Beginner Tip

Django Ninja is **not a replacement for Django** — it works *with* Django.

You still use Django models, ORM, and settings, but your APIs become much easier to manage.

### Key Components (You’ll Learn These Later)

| Component          | Purpose                          |
| ------------------ | -------------------------------- |
| NinjaAPI           | Main API application             |
| Routers            | Group related endpoints          |
| Schemas (Pydantic) | Define input/output data         |
| Endpoints          | Functions responding to requests |
| Docs               | Built-in Swagger / ReDoc         |

### Real-World Uses of Django Ninja

You can use Django Ninja to build:

* Backends for mobile apps (Flutter, React Native)
* APIs for web dashboards (React, Vue)
* Internal data services
* AI / ML prediction endpoints
* Banking or e-commerce systems

It’s flexible and production-ready.

### Quick Analogy

Think of Django Ninja as a friendly translator between your app and backend logic:

```
User → Request → Django Ninja → Response → User
```

You tell Django Ninja **what** to send and **where**, and it handles the rest.

### Common Terms You’ll Hear Often

| Term     | Meaning                              |
| -------- | ------------------------------------ |
| API      | Software communication interface     |
| Endpoint | A specific API path (e.g., `/hello`) |
| Request  | Data sent to the API                 |
| Response | Data returned from the API           |
| JSON     | Data format for APIs                 |
| Swagger  | Auto-generated API documentation     |

### Exercises

* Explain Django Ninja in your own words
* What’s the difference between Django Ninja and Django REST Framework?
* Create a `/greet` endpoint that returns your name
* Open `/api/docs` and test it


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://benjamin-sylvester.gitbook.io/django-ninja-made-simple/chapter-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.