Getting Started with Django Ninja

: A Step-by-Step Guide

This blog post will guide you through setting up Django Ninja, a fast, API framework for Django, designed to be easy to use and high performing. By the end of this tutorial, you’ll have a basic API up and running.

Step 1: Install Django and Django Ninja

First, let’s make sure you have Django installed. If not, create a new Django project. Open your terminal and follow these commands:

pip install django
django-admin startproject myproject
cd myproject

Next, install Django Ninja using pip:

pip install django-ninja

Step 2: Create a Django App (if needed)

If you don’t already have a Django app, create one to house your API:

python manage.py startapp myapp

Step 3: Configure Django Settings

Now, you need to tell Django about your new app. Open settings.py (located in your project directory, e.g., myproject/settings.py) and add 'myapp' to the INSTALLED_APPS list.

# myproject/settings.py
INSTALLED_APPS = [
    ...
    'myapp',
]

Step 4: Set Up Django Ninja

1. Create an API File: Inside your app directory (e.g., myapp), create a file named api.py. This is where you’ll define your API endpoints.

2. Define API Endpoints: Here’s a basic example of setting up Django Ninja with a couple of endpoints. This api.py file defines a simple API with endpoints for retrieving and creating items.

# myapp/api.py
from ninja import NinjaAPI
from pydantic import BaseModel

api = NinjaAPI()

class Item(BaseModel):
    name: str
    description: str = None

@api.get("/items/{item_id}")
def get_item(request, item_id: int):
    return {"item_id": item_id, "name": "Item Name", "description": "Item Description"}

@api.post("/items/")
def create_item(request, item: Item):
    return {"name": item.name, "description": item.description}

3. Include the API in Django URLs: Now, include the API endpoints in your project’s urls.py file.

# myproject/urls.py
from django.contrib import admin
from django.urls import path, include
from myapp.api import api

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', api.urls),  # Add this line
]

Step 5: Run Your Server

1. Apply Migrations: If you’ve made changes to your models, apply the migrations:

python manage.py makemigrations
python manage.py migrate

2. Start the Development Server: Fire up the Django development server:

python manage.py runserver

3. Test Your API: Open your web browser and go to http://127.0.0.1:8000/api/docs. You should see the interactive API documentation provided by Django Ninja. This is a great way to test your API endpoints.

Example Project Structure

Here’s how your project directory might look:

myproject/
    myproject/
        __init__.py
        settings.py
        urls.py
        wsgi.py
    myapp/
        __init__.py
        api.py
        models.py
        views.py
        urls.py
    manage.py

Testing the API

You can test the API by navigating to the following URL in your browser:

http://127.0.0.1:8000/api/items/2

API Documentation

Django Ninja automatically generates API documentation using OpenAPI and Swagger UI. You can access it at:

http://127.0.0.1:8000/api/docs

This documentation allows you to explore your API endpoints, test them, and understand the request and response structures.