Django Ninja Tutorial on CS 347

Part 1: Project setup & layout

Mon, 01 Jan 0001 00:00:00 +0000

Over eight parts, you’ll build TaskFlow, a task tracker for teams: projects, members, tasks, labels, comments and file attachments. This first part sets up a project layout that stays tidy as the API grows. Each app gets its own router and schemas, and one small module wires them together.

What you'll learn

How to lay out a multi-app project: one Router per app, one NinjaAPI for the project
How to mount routers with add_router() and group them in the docs with tags
How to generate input and output schemas with ModelSchema
How to nest one app’s endpoints under another app’s URL, with Path[...] for prefix parameters

Time: about 15 minutes

Part 2: Relations & computed fields

Mon, 01 Jan 0001 00:00:00 +0000

In Part 1, a task was a flat record whose project came back as a bare id. Real tasks have an assignee and labels, and clients want to see who and what those are without making a request for each one. In this part you’ll add those relations, return them as nested objects, compute a few values the model doesn’t store, and check how many queries each list costs.

What you'll learn

How to return related objects as nested schemas, while clients send plain ids
How to set a many-to-many relation after creating an object
How to compute a field with a resolve_<field> static method
How to read ORM annotations and reverse relations into a schema
How to spot N+1 queries and fix them with select_related and prefetch_related

Time: about 15 minutes

Part 3: Validation & workflows

Mon, 01 Jan 0001 00:00:00 +0000

So far, TaskFlow accepts almost anything a client sends: a title made of spaces is a valid task, and there’s no way to say a task is finished. In this part you’ll give tasks a status, a priority and a due date, validate input with field and model validators, add a PATCH endpoint for partial updates, and move tasks through a small workflow that rejects invalid status changes.

What you'll learn

How Django choices become enums in your schemas and in OpenAPI
How to write field validators and model validators, with your own error messages
What a 422 validation error looks like, and how to read it
How to accept partial updates with PatchDict, and what it changes about validation
How to reject an invalid state change with HttpError

Time: about 15 minutes

Part 4: Auth & permissions

Mon, 01 Jan 0001 00:00:00 +0000

Right now anyone who can reach the API can read and change every project. In this part you’ll add JSON Web Tokens, written from scratch with the standard library, require them on every endpoint, and then decide what each user may do: project memberships with roles, queries scoped to the user’s projects, and comments that only their author can edit.

What you'll learn

How to issue and verify JWT access and refresh tokens with nothing but the standard library
How to protect a whole API with an HttpBearer authenticator, and open up a few endpoints with auth=None
How to read the current user from request.auth
How to write one permission helper that returns 404 to non-members and 403 to members without the right role
How to scope every query to the user’s projects, and add object-level rules for comments

Time: about 15 minutes

Part 5: Filtering, search, ordering & pagination

Mon, 01 Jan 0001 00:00:00 +0000

GET /taskflow/api/projects/{project_id}/tasks/ returns every task of a project in one response. That’s fine for a handful, but a real team wants the tasks assigned to them, the overdue ones, or the ones mentioning “checkout”, and it doesn’t want a thousand of them at once. In this part you’ll add filters and search with a FilterSchema, let clients pick the sort order from a fixed list, and paginate tasks by page number and comments with a cursor.

Part 6: File uploads & forms

Mon, 01 Jan 0001 00:00:00 +0000

Tasks often come with files: a design mockup, a screenshot of a bug, a PDF from the client. In this part you’ll let members attach files to tasks. An upload is a multipart/form-data request instead of JSON, so you’ll combine a file parameter with form fields, validate the file’s size and type, store it with a plain FileField, and return an absolute URL for it.

What you'll learn

How to accept a file together with form fields using File[...] and Form[...]
How to validate an upload with a reusable annotated type, so errors come back as 422
How to configure MEDIA_ROOT and serve uploaded files during development
How to build absolute URLs in a response with a resolver that reads the request
How to delete a file together with its database row, behind a permission check

Time: about 15 minutes

Part 7: Testing

Mon, 01 Jan 0001 00:00:00 +0000

So far you’ve checked every feature by hand, with curl and the shell. In this part you’ll turn those checks into a pytest suite that runs in about half a second. Django Ninja’s TestClient calls your operations directly, so tests send JSON, form data, files and tokens without a running server.

What you'll learn

How to set up pytest and pytest-django for a Django Ninja project
How to write fixtures for users, projects with memberships, and logged-in clients
How TestClient calls an API, and how to send tokens, query strings and files with it
How to test validation errors, permissions and filters, and cover many cases with parametrize
How to keep uploads and password hashing from slowing down or littering your tests

Time: about 15 minutes

Part 8: OpenAPI polish & versioning

Mon, 01 Jan 0001 00:00:00 +0000

TaskFlow works and is tested. Other people will build against it, though, and for them the interactive docs are the API. In this last part you’ll make the generated schema say more: what the API is for, what each operation does, and what each field expects. Then you’ll ship a breaking change the safe way, as a version 2 that runs next to version 1.

What you'll learn

How to set the API’s title, version and description
How summaries, docstrings and Field(description=..., examples=...) show up in the schema
How to hide an internal endpoint and mark old ones as deprecated
How to run two NinjaAPI versions side by side, sharing the routers that didn’t change
How URL namespaces keep reverse() working with more than one API

Time: about 15 minutes