Prabodh Tuladhar - freeCodeCamp.org

How to Build a Scoped Note-Taking API with Django Rest Framework and SimpleJWT

Prabodh Tuladhar — Tue, 05 May 2026 19:23:01 +0000

If you've built a Django API and you're wondering how to add authentication so that each user can only access their own data, you're in the right place.

Most Django tutorials teach you session-based authentication. That works fine when your frontend and backend live on the same server. But the moment you separate them – say, a React app on Netlify talking to a Django API on PythonAnywhere – then sessions start to break down.

Cookies don't travel well across different domains, and suddenly your login system stops working.

That's where JSON Web Tokens (JWT) come in. JWTs give you a stateless, cookie-free way to authenticate users. They work seamlessly across domains, devices, and platforms. The server doesn't need to remember anything. It just verifies the token's signature and knows exactly who's making the request.

But authentication is only half the problem. Once you know who a user is, you still need to control what they can see. This is where scoping comes in.

Scoping means ensuring that each user can only access their own data. User A should never be able to read, edit, or delete User B's data (notes in our case), even if they somehow guess the right ID.

In this tutorial, you'll build a a personal note-taking API where users can register, log in with JWT tokens, and store notes that only they can access.

Along the way, you'll implement a custom user model, configure SimpleJWT for token-based authentication, and write scoped views that lock each user's data behind their own credentials.

What We'll Cover:

Prerequisities
What is JWT and Why Use It Over Session Authentication?
- How Session Authentication Works
- How JWT Authentication Works
Step 1: How to Set Up the Project and Install the Dependecies
Step 2: How to Create a Custom User Model
Step 3: How to Define the Note Model
- 3.2 How to Apply Migration
- 3.3 How to Register Models in the Admin
Step 4: How to Create the Serializer
- 4.1 How to Create UserSerializer
- 4.2 How to Create NoteSerializer
Step 5: How to Configure SimpleJWT
- 5.1 How to Update REST Framework Settings
- 5.2 How to Add Token URL Endpoints
Step 6: How to Build the Authentication Logic
Step 7: How to Implement Scoped Views
- 7.1 How to Create a NoteViewSet
- 7.2 Why This Matters: Preventing ID Enumeration Attacks
Step 8: How to Connect a URL
- 8.1 How to Create App-level URLs
- 8.2 How to Verify the Project-Level URLs
Step 9: How to Test the APIs with Postman
Step 10: How to Handle Token Expiration with Refresh Tokens
How You Can Improve This Project
Conclusion

Here's what this tutorial covers:

How to set up a custom user model (and why you should always do this)
How to configure SimpleJWT for access and refresh token authentication
How to build serializers that protect sensitive fields
How to scope your API views so users only see their own data
How to test the entire flow using Postman

Let's get started

Prerequisities

Before you begin, make sure you're comfortable with the following:

Django fundamentals: You should understand how Django projects and apps work, including models, views, URLs, and migrations.
Django REST Framework basics: You should be familiar with serializers, viewsets or API views, and how DRF handles requests and responses.
Basic command line usage: You'll run commands in your terminal throughout this tutorial.

Tools you'll need installed:

Python 3.8 or higher
pip (Python's package manager)
A code editor like Visual Studio Code
Postman (or any API testing tool) for testing your endpoints. You'll use this to send requests to your API.

What is JWT and Why Use It Over Session Authentication?

Before you write any code, it's important to understand what problem JWTs solve and why Django's built-in session authentication isn't always enough.

How Session Authentication Work

Django ships with a session-based authentication system. Here's how it works at a high level:

A user sends their username and password to the server.
The server verifies the credentials and creates a session which is a small record stored in the server's database that says "this user is logged in."
The server sends back a session ID as a cookie. The browser stores this cookie automatically.
On every subsequent request, the browser sends the cookie back to the server. The server looks up the session ID in its database and says "ah, this is User A. Let them through."

This works perfectly when your frontend and backend live on the same domain. The browser handles cookies automatically, and Django manages sessions in the database without you thinking about it.

But this approach has some limitations.

The cross-domain problem: If your React frontend lives at app.example.com and your Django API lives at api.example.com, cookies become tricky. Browsers enforce strict rules about which domains can send and receive cookies.

You can work around this with CORS (Cross-Origin Resource Sharing) headers and special cookie settings, but it adds complexity and can be fragile.
The scalability problem: Every active session is stored in the server's database. If you have 10,000 users logged in at the same time, that's 10,000 session records the server has to look up on every single request. As your application grows, this lookup becomes a bottleneck.
The mobile problem: Mobile apps don't handle cookies the same way browsers do. If you're building an API that will serve both a web app and a mobile app, session cookies create extra headaches.

How JWT Authentication Works

JWTs take a fundamentally different approach. Instead of storing session data on the server, they put the authentication information directly into the token itself.

Here's how the flow works:

A user sends their username and password to the server.
The server verifies the credentials and creates a JWT – a long encoded string that contains information like the user's ID and when the token expires.
The server sends this token back to the client. The client stores it (usually in memory or local storage).
On every subsequent request, the client includes the token in the request header. The server reads the token, verifies its signature, and says "this is User A. Let them through."

Notice the key difference: the server never stores anything.

It doesn't look up a session in a database. It simply reads the token, checks its cryptographic signature to make sure nobody tampered with it, and extracts the user information. That's why JWTs are called stateless – the server doesn't maintain any state about who is logged in.

This solves the cross-domain problem because tokens are sent in the request header, not as cookies. Headers work the same way regardless of which domain the request comes from.

This solves the scalability problem because the server doesn't store sessions. Verifying a token is a quick cryptographic check, not a database lookup.

This solves the mobile problem because any client that can send HTTP headers can use JWT. Mobile apps, desktop apps, other servers – they all work the same way.

Step 1: How to Set Up the Project and Install the Dependecies

1.1 How to Create the Project

Open your terminal, navigate to where you want your project to live, and run the following commands:

mkdir notes-project

cd notes-project

1.2 How to Create a Virtual Environment and Install the Required Dependencies

You will create a virtual environment here. Type the following command:

python3 -m venv venv

The above command creates a virtual environment inside a folder called venv. The first venv is the command and the second venv represents the name of the folder. You can name the folder anything though venv is usually preferred.

To activate the virtual environment, we need to use the following command:

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

You'll know it worked when you see (venv) at the beginning of your terminal prompt. From this point on, any Python packages you install will only exist inside this virtual environment.

With the virutal environment activated, install Django, Django Rest Framework, and Simple JWT Framework using the command:

pip install django djangorestframework djangorestframework-simplejwt

You can verify everything installed correctly by running:

pip list

You should see all three packages listed along with their dependencies.

1.3 How to Create the Project and the App

Run the following command to create the Django project:

django-admin startproject notes_core .

The dot at the end is important. It tells Django to create the project files in your current directory instead of creating an extra nested folder.

Now let's type this command to create the app:

python manage.py startapp notes

1.4 How to Register the App and Django Rest Framework (DRF)

Open notes_core/settings.py and add rest_framework and notes in the INSTALLED_APPS list:

Django now knows about your new app and the REST framework. Let's move on to the most important architectural decision you'll make for this project.

Step 2: How to Create a Custom User Model

If you've built Django projects before, you might have used Django's default User model. For quick prototypes, that works fine. But for any project you plan to grow or maintain, starting with a custom user model is a best practice you should never skip.

Here's why: Django's default User model uses a username field as the primary identifier. If you later decide you want users to log in with their email address instead, or you need to add a profile picture field, or a phone number, then you're stuck.

Using a custom user model gives you full control over what a "user" means in your app. Instead of being tied to a username, you can design login around something more practical, like email or phone_number for a fitness or mobile-based app. You can also include fields like role (doctor, patient, receptionist in a clinic system) or date of birth directly in the user model, instead of managing a separate profile.

It also helps future-proof your project. If you start with the default model and later decide to switch login from username to email, or add required fields, it becomes difficult and risky to change. Using a custom user model from the beginning avoids this problem and makes it much easier to adapt your authentication system as your app grows.

By creating a custom user model from the start, even if it's identical to the default one, you give yourself the freedom to make changes later without any of that pain.

2.1 How to Define the Custom User Model

Open notes/models/py and add the following code:

from django.contrib.auth.models import AbstractUser
from django.db import models

class CustomUser(AbstractUser):
    pass

You are importing Django’s built-in AbstractUser class.

Think of AbstractUser as a ready-made blueprint for a user. It already includes fields like username, password, email, first name, last name , and authentication logic.

The pass statement means you're not adding any extra fields yet.

But the key point is that this model is yours. So this model behaves exactly like Django’s default user model, but with one big advantage: you now have the flexibility to customize it later.

If three months from now you need to add a phone_number field or switch to email-based login, you just add a field to this class and run a migration.

from django.contrib.auth.models import AbstractUser
from django.db import models

class CustomUser(AbstractUser):
    phone_number = models.CharField(max_length=15)

You can also see all the fields that the CustomUser class has inherited from the AbstractUser class.

To do this we can use the Python shell. Type the following command:

python manage.py shell

When you type this command, make sure that the virtual environment is active:

After this, import the CustomUser model in the shell:

from notes.models import CustomUser

After that, type the following code:

[fields.name for field in CustomUser._meta.get_fields()]

The above statement lists out all the fields in the CustomUser class.

2.2 How to Tell Django to Use Your Custom User Model

Now comes the important bit. Open notes_core/settings.py and add this line:

AUTH_USER_MODEL = 'notes.CustomUser'

This setting tells Django to use your CustomUser model instead of the built-in one for everything authentication-related such as login, permissions, foreign keys, and so on.

There's no strict rule to where you need to add it, but the best practice is to add it near the end of the file.

You can see which user model Django is using by using the method get_user_model().

Open the Python shell again and import the get_user_model() method:

from django.contrib.auth import get_user_model

Then use get_user_model() and print the output:

user = get_user_model()
print(user)

You should see the name of our model being used:

If you hadn't added the AUTH_USER_MODEL in the settings.py file, then Django would have used the default user model:

Note: You'll need to do this before you run your first migration. If you run migrate before setting AUTH_USER_MODEL, Django creates tables for the default User model, and switching afterward becomes a headache.

2.3 How to Run Migrations

Now create and apply the initial migrations:

python manage.py makemigrations
python manage.py migrate

Django will create the necessary tables for your custom user model along with all the built-in Django tables.

We can again peek under the hood to see the SQL queries that Django used to create the tables especially the CustomUser table.

Type this command:

python manage.py sqlmigrate notes 0001

Here notes is the name of the app and 0001 represents the migration number.

And you should get this output:

Let's also create a superuser so you can access the admin panel later for debugging:

python manage.py createsuperuser

Fill in the username, email (optional), and password when prompted.

Step 3: How to Define the Note Model

Now let's create the data model for the core of your application. First add a new import to use the settings object.

from django.conf import settings

Then add the following code below the CustomUser class:

class Notes(models.Model):
    owner = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name='notes'
    )
    title = models.CharField(max_length=200)
    body = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    def __str__(self):
        return f"{self.title} (by {self.owner.username})"

Here's the complete model.py code:

from django.contrib.auth.models import AbstractUser
from django.db import models
from django.conf import settings

class CustomUser(AbstractUser):
    pass

class Notes(models.Model):
    owner = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name='notes'
    )
    title = models.CharField(max_length=200)
    body = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    def __str__(self):
        return f"{self.title} (by {self.owner.username})"

Let's walk through each field:

owner = models.ForeignKey(settings.AUTH_USER_MODEL, ...): Creates a relationship between each note and a user. The ForeignKey field tells Django that each note belogs to exactly one user but a user can have many notes.

Notice that we use settings.AUTH_USER_MODEL instead of directly importing CustomUser. This is the recommended practice because it keeps your code flexible. If you ever change the user model reference in settings, this foreign key adapts automatically.

The on_delete=models.CASCADE means that if a user is deleted, all their notes are deleted too.

The related_name='notes' lets you access a user's notes with user.notes.all().
title = models.CharField(max_length=200): Creates a text field for the task name, limited to 200 characters.
body = models.TextField(): Holds the actual note content. TextField has no character limit, so users can write as much as they need.
created_at = models.DateTimeField(auto_now_add=True): Automatically records the date and time when a task is created. You never need to set this manually.

The __str__() method gives each note a readable representation. Instead of seeing "Note object (1)" in the admin panel or during debugging, you'll see something like "Meeting Notes (by Solina)."

3.2 How to Apply Migration

Run the migration commands to create the Note table:

python manage.py makemigrations
python manage.py migrate

As before, we can see the exact SQL query Django used to create the notes table:

3.3 How to Register Models in the Admin

Open notes/admin.py and register both models so you can inspect data through the admin panel:

from django.contrib import admin
from .models import CustomUser, Notes

admin.site.register(CustomUser)
admin.site.register(Notes)

This is helpful during development when you want to quickly check whether data is being saved correctly.

Step 4: How to Create the Serializer

In DRF, a serializer is like a bridge between your database and the internet.

Django models store data as Python objects. But when you want to send that data to a frontend application (like React or a mobile app), you can't send Python objects. You need to send a format that everyone understands which is usually JSON.

Serializers perform three main jobs:

Serialization: Converting complex Python objects (Models) into Python dictionaries (which can be easily rendered into JSON).
Deserialization: Converting JSON data coming from a user back into complex Python objects.
Validation: Checking if the incoming data is correct before saving it to the database.

4.1 How to Create UserSerializer

Create a new file called notes/serializers.py and add the following code:

from rest_framework import serializers
from django.contrib.auth import get_user_model

User = get_user_model()
class UserSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True)

    class Meta:
        model = User
        fields = ['id', 'username', 'email', 'password']

    def create(self, validated_data):
        user = User.objects.create_user(
            username=validated_data['username'],
            email=validated_data.get('email', ''),
            password=validated_data['password']
        )
        return user

Let's break down this serializer.

The UserSerializer handles user registration.
User = get_user_model() gets the user model that you're using and stores in the variable User. In our case, we're using the CustomUser model
class UserSerializer(serializers.ModelSerializer):: Here you've created the UserSerializer class, which inherits ModelSerializer.

A ModelSerializer is a shortcut that automatically creates a serializers class with fields that are in the model class.

When we use a ModelSerializer, DRF inspects the model and automatically does these things:

1. Generates fields from the model so you don't have to
2. Automatically adds field validations that are present in the model
3. Implements create() and update() methods. A ModelSerializer knows which model to use and how to update and create it. You can override create() and update() methods if you need customized behaviors. You have overridden the create() method in the above code.
password = serializers.CharField(write_only=True): This line is crucial. The write_only=True flag means the password will be accepted during registration but will never appear in any API response. Without this, your API would send back the password (even if hashed) every time user data is returned.

So users can create accounts, but their passwords are never exposed back.
class Meta: Inside the Meta class, you tell the serializer which model to use. In this case, the model to use is User and the fields to be handled.
The create() method: This is the most important part. This method runs when we create a new user. Instead of using the default .create() method you have overridden it.

It's important to understand why we have overridden this method. The default create() method is not suitable for creating users securely.

By default this method stores the password in plain text format. This is a serious problem because passwords should never be stored in raw form. They need to be hashed so that even if the database is compromised, the passwords are never exposed.

Django provides a special method called create_user() that automatically handles this by hashing the password and setting up the user properly for authentication.

4.2 How to Create NoteSerializer

After the UserSerializer class, let's create the NoteSerializer class. The NoteSerializer handles the notes data

First of all, you need to add an import to the Notes class. Add the line from .models import Notes at the end of the last import.

Put this code below the UserSerializer class:

class NoteSerializer(serializers.ModelSerializer):
    owner = serializers.ReadOnlyField(source='owner.username')
    class Meta:
        model = Notes
        fields = ['id', 'owner', 'title', 'body', 'created_at']

Now let's break it down:

owner = serializers.ReadOnlyField(source='owner.username'): This is the most important line in the code. This makes the owner field read-only. That means the API will display who owns a note (showing their username), but no one can set or change the owner through the API.

Without this protection, a malicious user could send a POST request with "owner": 5 and assign their note to someone else's account, or worse, modify someone else's notes by reassigning ownership.

The source='owner.username' part tells DRF to display the owner's username instead of their numeric ID, which makes the API responses more readable.
class Meta: ...: As before the Meta class contains the model which the serializer use and the fields that the API will expose.

Here is the complete code in the serializers.py file

from rest_framework import serializers
from django.contrib.auth import get_user_model
from .models import Notes

User = get_user_model()
class UserSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True)
    class Meta:
        model = User
        fields = ['id', 'username', 'email', 'password']

    def create(self, validated_data):
        user = User.objects.create_user(
            username=validated_data['username'],
            email=validated_data.get('email', ''),
            password=validated_data['password']
        )
        return user

class NoteSerializer(serializers.ModelSerializer):
    owner = serializers.ReadOnlyField(source='owner.username')
    class Meta:
        model = Notes
        fields = ['id', 'owner', 'title', 'body', 'created_at']

Step 5: How to Configure SimpleJWT

Now let's set up the authentication system. This is where you tell DRF to use JWT for authentication instead of sessions. This step is crucial because without it, DRF will default to session-based auth.

SimpleJWT provides a complete JWT implementation for DRF, so you don't have to build token generation, signing, or verification from scratch.

The access token is what your client sends with every API request. It's short-lived by design. Think of it like a visitor badge at an office building: it gets you through the door, but it expires at the end of the day. If someone steals it, the damage is limited because it stops working soon.

The refresh token is longer-lived and has a single purpose: getting a new access token when the current one expires. The client stores it securely and only sends it to one specific endpoint. Think of it like your employee ID card. You use it to get a new visitor badge each morning, but you don't flash it at every door.

This separation exists for security. If the short-lived access token is compromised (which is more likely since it's sent with every request), the attacker has a narrow window before it expires. The refresh token, which is sent less frequently, has a lower risk of interception.

Let's look at how the access and refresh token work together

User logs in, server gives both access token and refresh token
User makes requests using the access token
Access token expires
App sends refresh token to server
Server checks it and gives a new access token
User continues without logging in again

5.1 How to Update REST Framework Settings

Open notes_core/settings.py and add the following code:

from datetime import timedelta
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),

    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated',
    ),
}

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=30),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
}

Let's unpack what each section does.

The DEFAULT_AUTHENTICATION_CLASSES setting tells DRF to use JWT as the authentication method for all API endpoints. Every incoming request will be checked for a valid JWT token in the Authorization header.

The DEFAULT_PERMISSION_CLASSES setting sets IsAuthenticated as the global permission policy. This means every endpoint in your API is locked down by default. Only users with a valid token can access any endpoint.

This is a secure-by-default approach: instead of remembering to protect each view individually, everything is protected, and you explicitly open up the endpoints that need to be public (like the registration endpoint, which you'll handle in the next step).

The SIMPLE_JWT dictionary controls token behavior. The access token lasts 30 minutes. This is the token clients include in every request. If someone intercepts it, the damage is limited to a 30-minute window. The refresh token lasts one day.

When the access token expires, the client can use the refresh token to get a new access token without forcing the user to log in again. The duration of the refresh token is 1 day. This means after 1 day, the user must log in again with their username and password. You'll see exactly how this works later when you test with Postman.

5.2 How to Add Token URL Endpoints

SimpleJWT provides ready-made views for obtaining and refreshing tokens. You just need to wire them up to URLs.

Open notes_core/urls.py and update it with the following code:

from django.contrib import admin
from django.urls import path, include
from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('notes.urls')),
    path('api/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
]

The token/ endpoint accepts a username and password, and returns an access token and a refresh token.

The token/refresh/ endpoint accepts a refresh token and returns a new access token. You'll see these in action during testing.

Step 6: How to Build the Authentication Logic

Open notes/views.py and add the following:

from rest_framework import generics, permissions
from django.contrib.auth import get_user_model
from .serializers import UserSerializer

User = get_user_model()

class RegisterView(generics.CreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = [permissions.AllowAny]

Now let's walk through this code.

The first section are the imports and after that we have used the the get_user_model() method to get the CustomUser model.

Now the main part is RegisterView class. The class inherits from generics.CreateAPIView which is a built in DRF view designed specifically for handling POST requests that create new objects.

Because of this, you don’t have to manually write the logic for handling POST requests, validating data, or saving to the database. DRF does all of that for you behind the scenes.

Inside the class, queryset = Users.objects.all() defines the set of user objects this view can work with.

The serializer_class = UserSerializer tells the view which serializer to use for validating incoming data and creating the user.

Finally permission_classes = [permissions.AllowAny] overrides the global IsAuthenticated permission you set earlier in the value of DEFAULT_PERMISSION_CLASSES .

This means that anyone can access the registration endpoint, even if they aren't logged in. This makes sense for a registration endpoint because new users won’t have accounts yet.

Every other view in your API will inherit the global IsAuthenticated permission, so only this registration endpoint is open.

Step 7: How to Implement Scoped Views

This is the heart of the tutorial. You've set up authentication so the API knows who is making a request. Now you need to make sure each user can only interact with their own notes.

Think of it this way: authentication is the lock on the front door of an apartment building. It keeps strangers out. But scoping is the lock on each individual apartment. Just because you live in the building doesn't mean you can walk into your neighbor's apartment.

Without scoping, an authenticated user could potentially see every note in the database, or worse, modify notes that belong to someone else. Two method overrides on your viewset prevent this entirely.

7.1 How to Create a NoteViewSet

Now let's create the NoteViewSet. First add these imports to the top of the file. We're importing the viewsets, serializers, and model.

from .models import Note
from .serializers import UserSerializer, NoteSerializer
from rest_framework import generics, viewsets, permissions

Add the following to notes/views.py, below the RegisterView:

class NoteViewSet(viewsets.ModelViewSet):
    serializer_class = NoteSerializer

    def get_queryset(self):
        return Notes.objects.filter(owner=self.request.user).order_by('-created_at')

    def perform_create(self, serializer):
        serializer.save(owner=self.request.user)

Now let's talk about this code in detail.

You've created a new class called NoteViewSet which inherits from the DRF class ModelViewSet. This gives you full CRUD operations, meaning you can list notes and retrieve a single note, as well as create, update, and delete a note.

The next part serializer_class = NoteSerializer tells Django to use the NoteSerializer class to convert between Python objects and JSON.

But the magic is the two methods that you are overriding: get_queryset() and perform_create().

The get_queryset() method controls which notes the API returns. If you didn't override this method, it would return Note.objects.all() (which would give every user access to every note in the database).

But here, you've overridden this method so that it filters notes by the current user.

Next is the perform_create() method, which is called when the note is saved. You've overridden this method so that it saves the notes of the user who's currently logged in. If you hadn't overridden the this method, it would return all the notes regardless of the logged in user.

Notice that you have passed self.request.user parameters in to the filter() function. This is the code that attaches the logged-in user as the owner of the note.

Remember how you made the owner field read-only in the serializer? This is the other half of that security measure.

The user can't set the owner through the API request, and the server automatically sets it to whoever is authenticated. These two pieces work together to make ownership tamper-proof.

7.2 Why This Matters: Preventing ID Enumeration Attacks

Without get_queryset filtering, your API might allow something like this: a user sends a GET request to /api/notes/42/ and sees a note that belongs to someone else, simply because they guessed the ID.

This is called an ID enumeration attack — an attacker cycles through IDs (1, 2, 3, 4...) to discover and access other people's data.

With your scoped get_queryset, even if User B sends a request to /api/notes/42/ and note 42 belongs to User A, the viewset won't find it in User B's filtered queryset. DRF will return a 404 — as far as User B is concerned, that note doesn't exist.

Step 8: How to Connect a URL

Now you need to wire up the views to URL paths so the API knows which view to call for each endpoint.

8.1 How to Create App-level URLs

Create a new file called notes/urls.py and add the following:

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import RegisterView, NoteViewSet

router = DefaultRouter()
router.register(r'notes', NoteViewSet, basename='note')

urlpatterns = [
    path('register/', RegisterView.as_view(), name='register'),
    path('', include(router.urls)),
]

The DefaultRouter automatically generates URL patterns for the NoteViewSet. Since you're using a ModelViewSet, the router creates endpoints for listing all notes, creating a note, retrieving a single note, updating a note, and deleting a note — all from that single router.register call.

The basename='note' parameter is required here because your viewset doesn't have a queryset attribute defined directly on the class (you're using get_queryset instead). DRF uses the basename to generate the URL pattern names like note-list and note-detail.

8.2 How to Verify the Project-Level URLs

Make sure your notes_core/urls.py looks like this (you set this up in Step 5, but let's confirm):

from django.contrib import admin
from django.urls import path, include
from rest_framework_simplejwt.views import (
    TokenObtainPairView,
    TokenRefreshView,
)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('notes.urls')),
    path('api/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
]

Here's the full picture of your API's URL structure:

Endpoint	Method	Description
`api/register/`	POST	Create a new user account
`api/token/`	POST	Get access and refresh tokens
`api/token/refresh/`	POST	Get a new access token using a refresh token
`api/notes/`	GET	List all notes for the authenticated user
`api/notes/`	POST	Create a new note
`api/notes//`	GET	Retrieve a specific note
`api/notes//`	PUT/PATCH	Update a specific note
`api/notes//`	DELETE	Delete a specific note

Start the development server to make sure everything runs without errors:

python manage.py runserver

If the server starts without complaints, your code is wired up correctly.

Step 9: How to Test the APIs with Postman

Building the API is one thing. Proving it works is another. Let's walk through the entire flow using Postman, from registering a user to demonstrating that scoping actually works.

If you haven't used Postman before, it's a tool that lets you send HTTP requests to your API and inspect the responses. You can download it from postman.com/downloads.

Alternatively, you can use curl from the command line or any other API testing tool you're comfortable with.

Make sure your development server is running before proceeding.

9.1 How to Register a User

Open Postman:

Create a new request:

Method	POST
URL	`http://127.0.0.1:8000/api/register/`
Body tab	Select "raw" and choose "JSON" from the dropdown
Body Content	{ "username": "priya", "email": "priya@example.com", "password": "securepassword123" }

Click Send. You should get a 201 Created response with the user data (without the password, thanks to your write_only=True field) which you wrote in the UserSerializer class.

9.2 How to Obtain Access and Refresh Tokens

Now log in to get your JWTs:

Method	POST
URL	`http://127.0.0.1:8000/api/token/`
Body	{"username" : "priya", "password" : "securepassword123"}

You'll get a response with access and refresh tokens.

Copy the access token. You'll need it for every subsequent request. Also save the refresh token, as you'll use it later.

A JWT is only encoded and not encrypted. The encoding is merely a way to transform the data into a safe, standard string format that can be easily transmitted over the internet.

Any one can peel through the encoding to see the data. This is done using base64url encoding.

We can use the Python library pyjwt to decode JWTs or use any of the online sites to decode. It's important to note that you should use online sites with caution since JWTs may contain sensitive information.

For this demo, we'll use site called jwt.io.

Open the site and paste in the access token that you have just created:

The JWT has three parts: the header, the payload, and the signature.

The header sections tells you how the header is signed. In this case it is signed using the HS256 algorithm.

The payload is where the actual data or claim lives. It contains standard claims such as token types, expiration time ( exp ), issued at time ( iat ), and custom claims.

The signature section is used to verify integrity. You can't decode it to meaningful data. This section ensures that the token wasn't tampered with.

9.3 How to Create a Note

Now use the access token to create a note:

Method	POST
URL	`http://127.0.0.1:8000/api/notes/`
Header tab:	Add a new header:
Key: Authorization, Value: Bearer
Body	{'title': 'My note', 'body': 'This contains secret information'}

Notice that you don't include an owner field. That's handled automatically by perform_create. You should get a 201 Created response:

You can create a few more notes, so that we have some data to work with.

9.4 How to List Your Notes

Now to fetch all of Priya's notes:

Method	GET
URL	`http://127.0.0.1:8000/api/notes/`
Header tab:	Same Authorization: Bearer header

You should see all the notes created, sorted by most recent first.

9.5 How to Demonstrate Scoping

Let's prove that a second user can't view the first user's notes.

First, register the second user.

Send a POST request to http://127.0.0.1/api/register with the following data:

Method	POST
URL	`http://127.0.0.1:8000/api/register/`
Body tab	Select "raw" and choose "JSON" from the dropdown
Body Content	{ "username": "sujan", "email": "sujan@example.com", "password": "anotherpassword123" }

Then get tokens for Sujan by sending a POST request to http://127.0.0.1:8000/api/token/ with Sujan's credentials (username and password) and then copy Sujan's access token.

Now send a GET request to http://127.0.0.1:8000/api/notes/ using Sujan's token in the Authorization header.

The response should be an empty list since this user hasn't created any notes:

More importantly, Priya's notes are completely invisible to him. Even if Sujan tries to access a specific note by ID – say, http://127.0.0.1:8000/api/notes/1/ – he'll get a 404 Not Found response, not a 403 Forbidden.

This is intentional. A 404 Not Found doesn't reveal that the note exists, while a 403 Forbidden would confirm its existence to a potential attacker.

A 403 Forbidden response is like a door with a sign: “Authorized personnel only”. You now know something important is inside. A 404 Not Found response is like a blank wall. You don’t even know a room exists.

Now that you know why we've used the 404 response instead of 403, let's demonstrate this.

First, I'll access Priya's individual note using her credentials and her access token:

Now, I'll change the access token and put Sujan's (new user) access token:

You can see that using the new user's token to access the previous user's note leads to 404 Not Found response.

Step 10: How to Handle Token Expiration with Refresh Tokens

Access tokens are deliberately short-lived (30 minutes in your configuration). This limits the window of damage if a token is stolen.

But you don't want users to re-enter their credentials every 30 minutes. That's what refresh tokens are for.

When Priya's access token expires, her API requests will start returning 401 Unauthorized responses. Instead of logging in again, the client sends the refresh token to get a fresh access token.

Method	POST
URL	`http://127.0.0.1:8000/api/token/refresh/`
Body tab	Select "raw" and choose "JSON" from the dropdown
Body Content	{ refresh: < Priya's refresh token >}

Replace your old access token with this new one, and you're good for another 30 minutes. The refresh token itself lasts for one day, so the user only needs to fully log in again once every 24 hours.

In a real application, the frontend client handles this automatically. When an API call returns a 401, the client catches it, sends the refresh token to get a new access token, and retries the original request — all without the user noticing.

Here's what that flow looks like in pseudocode:

Client sends request with access token
Server responds with 401 (token expired)
Client sends refresh token to /api/token/refresh/
Server responds with a new access token
Client retries the original request with the new access token
Server responds with the data

If the refresh token itself has expired (after 24 hours in your configuration), step 4 will also return a 401. At that point, the user truly needs to log in again with their username and password. This is the intended behavior: it means even a stolen refresh token has a limited useful life.

How You Can Improve This Project

This API is functional and secure, but there's plenty of room to build on it. Here are some directions you could take.

Add search and filtering. Let users search their notes by title or body text. You can use DRF's SearchFilter and django-filter to add query parameters like ?search=meeting to the notes list endpoint.
Add categories or tags. Create a Category model and add a foreign key to Note, or use a many-to-many relationship for tags. This would let users organize their notes and filter by category.
Add pagination. Once a user has hundreds of notes, returning them all in a single response becomes slow. DRF has built-in pagination classes that let you return notes in pages of 10, 20, or whatever size you choose.
Deploy to a production server. The API currently runs on your local machine. You could deploy it to platforms like PythonAnywhere, Railway, or Render to make it accessible from anywhere. You'd need to configure a production database (like PostgreSQL), set a secure SECRET_KEY, and serve the application behind HTTPS.
Build a frontend. Connect a React, Next.js, or Vue.js frontend to this API. Store the JWTs in the client and implement the token refresh flow so users stay logged in seamlessly.
Add token blacklisting. SimpleJWT supports token blacklisting, which lets you invalidate refresh tokens when a user logs out. Without this, a refresh token remains valid until it expires, even after the user "logs out."

Each of these improvements builds on the patterns you've already learned and will deepen your understanding of Django, DRF, and API design.

Conclusion

You've built a fully functional, secure note-taking API with Django, Django REST Framework, and SimpleJWT. Along the way, you learned some fundamental concepts that apply to any API you'll build in the future.

You started with a custom user model — a small decision at the beginning that saves you from a painful migration later. You configured JWT authentication so your API can serve mobile clients and decoupled frontends that can't rely on session cookies.

You built serializers that protect sensitive data by keeping passwords write-only and ownership read-only. Most importantly, you implemented scoped views that ensure each user's data is completely isolated from everyone else's.

The patterns you practiced here — overriding get_queryset to filter by the current user, overriding perform_create to assign ownership automatically, and using read-only fields to prevent data tampering — are the same patterns you'll use in production APIs handling real user data.

The best way to solidify what you've learned is to keep building. Try adding search and filtering, build a React frontend that consumes this API, or start a completely new project may be a task manager, a journal app, or a bookmarks API using the same JWT and scoping patterns. The core workflow stays the same. Only the models and business logic change.

How to Build and Deploy a Fitness Tracker Using Python Django and PythonAnywhere - A Beginner Friendly Guide

Prabodh Tuladhar — Fri, 03 Apr 2026 17:57:00 +0000

If you've learned some Python basics but still feel stuck when it comes to building something real, you're not alone. Many beginners go through tutorials, learn about variables, functions, and loops, and then hit a wall when they try to create an actual project.

The gap between "I know Python syntax" and "I can build a working web app" can feel enormous. But it does not have to be.

In this tutorial, you'll build a fitness tracker web application from scratch using Django, one of the most popular Python web frameworks. By the end, you'll have a fully functional app running live on the internet – something you can show to friends, add to your portfolio, or keep building on.

Here's what you'll learn:

How Django projects and apps are structured
How to define database models to store workout data
How to create views that handle user requests
How to build HTML templates that display your data
How to connect URLs to views so users can navigate your app
How to deploy your finished app to PythonAnywhere so anyone can access it

The app itself is straightforward: you can log a workout by entering an activity name, duration, and date. You can then view all your logged workouts on a separate page. It's simple, but it covers the core Django concepts you need to build much bigger things later.

Let's get started.

Prerequisites
What You Are Going Build
Step 1: How to Set Up Your Django Project
Step 2: How to Create a Django App
- 2.1 How to Generate the App
- 2.2 How to Register the App
Step 3: How to create a Workout Model
- 3.1 How to Define the Model
Step 4: How to Apply Migrations
- 4.1 How to Generate the Migration
- 4.2 How to Apply the Migration
Step 5: How to Register the Model in the Admin Panel
- 5.2 How to Create a Superuser
- 5.3 How to Access the Admin Panel
Step 6: How to Create Views for the App
- 6.1 How to Create a Form Class
- 6.2 How to Write Views
Step 7: How to Create Templates
Step 8: How to Connect URLs
- 8.1 How to Create App Level URLs
- 8.2 How to Link App URLs to project
Step 9: How to Test the Application Locally
Step 10: How to Prepare for Deployment
- 10.1 How to Update Settings for Production
Step 11: How to Deploy Your Django App on PythonAnywhere
Common Mistakes and How to Fix Them
How You Can Improve This Project
Conclusion

Prerequisites

Before you begin, make sure you are comfortable with the following:

Python fundamentals: You should understand variables, functions, lists, dictionaries, and basic control flow (if/else statements and loops).

Basic command line usage: You'll be running commands in your terminal throughout this tutorial. You should know how to open a terminal, navigate between folders, and run commands. If you're on Windows, you can use Command Prompt or PowerShell. On macOS or Linux, the default Terminal app works well.

Tools you'll need installed:

Python 3.8 or higher. You can check your version by running python --version or python3 --version in your terminal. If you don't have Python installed, download it from python.org
pip. This is Python's package manager. It usually comes bundled with Python. You can verify by running pip --version or pip3 --version. Note the commands python3 and pip3 tell the terminal that you are explicitly using Python Version 3
A code editor. Visual Studio Code is a great free option, but you can use any editor you're comfortable with.

That's everything. You don't need prior Django experience or web development knowledge. This tutorial will walk you through each step.

What You Are Going Build

The fitness tracker you will build has two main features:

A form to log workouts. You will enter the name of an activity (like "Running" or "Push-ups"), how long you did it (in minutes), and the date. When you submit the form, Django saves that workout to a database.

A page to view all your workouts. This page displays every workout you have logged, showing the activity, duration, and date in a clean list.

Here's how data flows through the app at a high level:

You fill out the workout form in your browser and click submit.
Your browser sends that data to Django.
Django's view function receives the data, validates it, and saves it to the database.
When you visit the workouts page, Django's view function pulls all saved workouts from the database.
Django passes that data to an HTML template, which renders it as a page your browser can display.

This request-response cycle is the foundation of how Django works. Once you understand it, you can build almost anything.

Step 1: How to Set Up Your Django Project

Every Django project starts with a few setup steps. You'll create an isolated Python environment, install Django, and generate the initial project structure.

1. 1 How to Create a Virtual Environment

A virtual environment is a self-contained folder that contains its own Python interpreter and installed packages for a specific project. This keeps your project's dependencies separate from other Python projects on your computer. This separation prevents version conflicts and keeps setups consistent.

For example, one project might require an older version of Django, while another needs the latest version, and a virtual environment allows both to work smoothly on the same system.

Without it, global installations can clash, break projects, and make setups hard to reproduce. Over time, the system environment becomes cluttered with unused or incompatible packages making debugging and maintenance more difficult.

Now let's set it up.

Open your terminal, and navigate to where you want your project to live and run the following command

mkdir fitness-tracker
cd fitness-tracker

The first command creates a new folder called fitness-tracker. The second command moves you into that folder.

You'll create the Python virutal environment here.

python3 -m venv venv

By using the ls command, you can see that we've created the virtual environment folder.

To activate the virtual environment, we need to use the following command:

On macOS/Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

You'll know it worked when you see (venv) at the beginning of your terminal prompt. From this point on, any Python packages you install will only exist inside this virtual environment.

1.2 How to Install Django

With your virtual environment activated, install Django using pip:

pip install django

This downloads and installs the latest stable version of Django. You can verify the installation by running:

python3 -m django --version

After running both these commands, you should see Django being installed and the version number:

1.3 How to Create the Project

We have finished installing Django. Now let's create a Django project. Django provides a command line utility that generates the boilerplate files that you need. Type the following command:

django-admin startproject fitness_project .

The command creates a folder named fitness-project. Notice the dot at the end of the command. The dot at the end is important. It tells Django to create the project files in your current directory instead of creating an extra nested folder.

Now that we've created our Django project, let's open the project in your favourite text editor and look at folder structure.

You'll notice that the folder already comes with a bunch of files.

1.4 How to Run the Development Server

Now let's make sure everything is working. You'll need to run a server for this. Type the following command:

python manage.py runserver

You can type this command in the terminal with the virtual environment activated or you can use the integrated terminal if you're using VS Code. I'll be using the integrated terminal from this point on.

Open your browser and go to http://127.0.0.1:8000/. You should see Django's default welcome page with a rocket ship graphic confirming that your project is set up correctly.

Press Ctrl + C in your terminal to stop the server when you're ready to move on.

Step 2: How to Create a Django App

In Django, a project is the overall container for your entire web application, while an app is a smaller, self-contained module inside that project that focuses on a specific piece of functionality.

A useful way to picture this is to think of a house. The project is the whole house. Each app is like a room inside that house. One room might be a kitchen, another a bedroom, each designed with a clear purpose. In the same way, a Django app is built to handle one responsibility, such as authentication, payments, or in this case, workout tracking.

Now, here's the important part: why not just put everything into one big project instead of using apps? You technically could, especially for very small projects. But as your application grows, that approach quickly becomes difficult to manage.

By using apps, you naturally separate concerns. It also makes collaboration smoother, since different people can work on different apps without constantly stepping on each other’s code.

Another major benefit is reusability. Since apps are modular, you can take an app from one project and reuse it in another.

For example, if you build a workout tracking app once, you could plug it into a completely different Django project later without rebuilding it from scratch. Later, you might create a completely different project, say a fitness coaching platform or a health dashboard. Instead of rebuilding the tracking feature from scratch, you can reuse the same app.

For this project, you'll create a single app called tracker that handles everything related to logging and displaying workouts.

2.1 How to Generate the App

Make sure you're in the same directory as the manage.py file, then run the following code:

python manage.py startapp tracker

This create a new folder called tracker with the following following structure:

Each file has its own purpose. You'll work with models.py, views.py and admin.py throughout this project.

2.2 How to Register the App

Django doesn't automatically know about your new app. You need to tell it by adding the app to the INSTALLED_APPS list in settings.py file.

Open fitness_project/settings.py and find the INSTALLED_APPS list. Add the name of the app, that is tracker, to the end of the list:

You'll notice that a number of apps have already been installed automatically by Django. This is part of Django’s “batteries-included” philosophy, where many common features are ready to use out of the box.

Here is a short summary of what each of the apps does.

App Name	Purpose
django.contrib.admin	Powers the built-in admin dashboard, letting you manage your data through a web interface.
django.contrib.auth	Handles users, login systems, permissions, and password management.
django.contrib.contenttypes	Helps Django track and manage relationships between different models.
django.contrib.sessions	Stores user session data, so users stay logged in across requests.
django.contrib.messages	Lets you show temporary notifications like success or error messages.
django.contrib.staticfiles	Manages static assets such as CSS, JavaScript, and images

Now Django knows your tracker app exists and will include it when running the project.

Step 3: How to Create a Workout Model

A model in Django is a Python class that defines the structure of your data. Each model maps directly to a table in your database. Each attribute on the model becomes a column in that table.

Think of a model as a blueprint for a spreadsheet. The class name is the name of the spreadsheet, and each field is a column header. Every time you save a new workout, Django creates a new row in that spreadsheet.

3.1 How to Define the Model

Open tracker/models.py and replace its contents with this code:

from django.db import models

class Workout(models.Model):
    activity = models.CharField(max_length=200)
    duration = models.IntegerField(help_text="Duration in minutes")
    date = models.DateField()

    def __str__(self):
        return f"{self.activity} - {self.duration} min on {self.date}"

Let's discuss what each part does:

activity = models.CharField(max_length=200) creates a text fields that can hold up to 200 characters. This is where you'll store the name of the exercise like "Running" or "Cycling".
duration = models.IntegerField(help_text="Duration in minutes") creates a whole number field for storing how many minutes the workout lasted. The help_text parameter adds a hint that will appear in forms and the admin panel.
date = models.DateField() creates a date field for recording when the workout happened.

The __str__() method defines how a Workout object appears when printed or displayed in the admin panel. Instead of seeing something unhelpful like "Workout object (1)," you will see "Running - 30 min on 2025-03-15."

Step 4: How to Apply Migrations

You've defined your model, but Django hasn't created the actual database table yet. To do that, you need to run migrations.

Migrations are Django's way of translating your Python model definitions into database instructions. Migrations are done in two steps.

When you change a model – maybe by adding a field, removing a field, or renaming one – you create a new migration that describes that change. You can do this using the makemigrations command.

Then you apply the migration using the migrate command and Django updates the database to match.

This two-step process of first detecting the change and then applying the change gives you a reliable record of every change to your database structure over time.

4.1 How to Generate the Migration

Run the following command in the integrated terminal:

python manage.py makemigrations

You should see output like this:

Migrations for 'tracker': tracker/migrations/0001_initial.py 
    + Create model Workout

Django inspected your Workout model and created a migration file that describes how to build the corresponding database table. You can find this file at tracker/migrations/0001_initial.py if you want to look at it, but you don't need to edit it.

4.2 How to Apply the Migration

Now tell Django to execute that migration and actually create the table in the database:

python manage.py migrate

You'll see several lines of output as Django applies not just your migration, but also the default migrations for Django's built-in apps (authentication, sessions, and so on).

When it finishes, your database has a table ready to store workouts.

When the migrate command runs, we can see the exact SQL commands that Django used to build and change the database. Though this isn't required for creating the application, it's always good to know what's happening under hood.

Run this command:

python manage.py sqlmigrate tracker 001

And you should get this output:

The 001 you added at the end is the migration number and represents first version of the database schema.

In practice, your workflow usually looks like this: you change your models, run makemigrations to generate the migration files, and then run the migrate command to apply those changes to the database.

Step 5: How to Register the Model in the Admin Panel

Django comes with a powerful admin interface built in. It gives you a graphical way to view, add, edit, and delete records in your database without writing any extra code. This is incredibly useful during development because you can quickly test your models and see your data.

But by default, it doesn’t know:

Which models you want to manage
How you want them displayed

So you register models in admin.py to tell Django to include the specific model in the admin interface.

5.1 How to Add Model to Admin

Open tracker/admin.py and add the following code:

from django.contrib import admin
from .models import Workout

admin.site.register(Workout)

This single line tells Django to include the Workout model in the admin interface.

5.2 How to Create a Superuser

To access the admin panel, you need an admin account. Create one by running:

python manage.py createsuperuser

Django will prompt you for a username, email address, and password. Choose something you will remember. The email is optional – you can press Enter to skip it.

5.3 How to Access the Admin Panel

Start the development server:

python manage.py runserver

Then navigate to http://127.0.0.1:8000/admin/ in your browser. Log in with the credentials you just created.

You should see the Django administration dashboard with a "Tracker" section containing your "Workouts" model.

Try clicking "Add" to create a couple of test workouts. This will confirm that your model is working correctly before you build the rest of the app.

Step 6: How to Create Views for the App

A view in Django is a Python function (or class) that receives a web request and returns a web response. That response could be an HTML page, a redirect, a 404 error, or anything else a browser can handle.

Views are where your application logic lives. They decide what data to fetch, what processing to do, and what to show the user.

For this app, you need two views: one to display the form where users add a workout, and one to display the list of all saved workouts.

6.1 How to Create a Form Class

Before writing the views, you need a Django form that handles the workout input.

Django forms are a built-in way to handle user input like login forms, contact forms, or anything that collects data from a user. Instead of manually writing HTML, validating inputs, and handling errors, Django gives you a structured way to do all of that in one place.

Most user inputs are based on the models you’ve created, and Django can automatically generate forms from those models using ModelForms, which speeds things up significantly.

Let's create a new file called forms.py in the tracker folder and add the following code:

from django import forms
from .models import Workout

class WorkoutForm(forms.ModelForm):

    class Meta:
        model = Workout
        fields = ['activity', 'duration', 'date']
        widgets = {
            'date': forms.DateInput(attrs={'type': 'date'}),
        }

In the above code, the ModelForm automatically generates form fields based on the Workout model. The widgets dictionary tells Django to render the date field as an HTML date picker instead of a plain text input.

We can actually see the forms being automatically created by Django. For this we need to enter the shell. In the terminal, type the following command:

python manage.py shell

Now lets import the WorkoutForm class that we just created.

Type the following code:

from tracker.forms import WorkoutForm

Notice that we've given the name of the app as well when we imported the form.

Then create an object of the WorkoutForm class and print it.

from tracker.forms import WorkoutForm
workoutform = WorkoutForm()
print(workoutform)

You should get the following output:

You can see that all the model fields have been renderd as HTML forms and the date field has been created as a date type that is type="date" instead of plain text.

6.2 How to Write Views

As we've discussed above, our project has two views: one to add a workout and the other to display all the saved workouts.

First, let's create a view to add a workout. In the tracker/views.py file, type the following code:

from django.shortcuts import render, redirect
from .models import Workout

# view to list all workouts
def workout_list(request):
    workouts = Workout.objects.all().order_by('-date')
    return render(request, 'tracker/workout_list.html', {'workouts': workouts})

Let's walk through this view:

The workout_list view handles the page that displays all workouts.
It queries the database for every Workout object, orders them by date (most recent first, thanks to the - prefix), and passes that list to a template called workout_list.html.
The render function combines the template with the data and returns the finished HTML page.

To create the logic to add a workout, first add the Workout form import at the end of the import section. Then add the following code after the workout_list view:

from django.shortcuts import render, redirect
from .models import Workout
from .forms import WorkoutForm

# view to list all the workouts
def workout_list(request):
    workouts = Workout.objects.all().order_by('-date')
    return render(request, 'tracker/workout_list.html', {'workouts': workouts})

# view to add a workout
def add_workout(request):
    if request.method == 'POST':
        form = WorkoutForm(request.POST)
        if form.is_valid():
            form.save()
            return redirect('workout_list')
    else:
        form = WorkoutForm()
    return render(request, 'tracker/add_workout.html', {'form': form})

The add_workout view handles both displaying the empty form and processing submitted form data.
When a user first visits the page, the request method is GET, so Django creates a blank form and renders it.
When the user fills out the form and clicks submit, the request method is POST. Django then validates the submitted data, saves it to the database if everything is correct, and redirects the user to the workout list page.
If the data isn't valid, Django re-renders the form with error messages.

Here is the complete views code:

from django.shortcuts import render, redirect
from .models import Workout
from .forms import WorkoutForm

# view to list all workouts
def workout_list(request):
    workouts = Workout.objects.all().order_by('-date')
    return render(request, 'tracker/workout_list.html', {'workouts': workouts})

# view to add a workout
def add_workout(request):
    if request.method == 'POST':
        form = WorkoutForm(request.POST)
        if form.is_valid():
            form.save()
            return redirect('workout_list')
    else:
        form = WorkoutForm()
    return render(request, 'tracker/add_workout.html', {'form': form})

Step 7: How to Create Templates

Templates are HTML files that Django fills in with dynamic data. They're the front end of your application: the part users actually see in their browser.

7.1 How to Set Up the Template Directory

Django looks for templates inside a templates folder within each app. Create the following folder structure inside your tracker app.

tracker/templates/tracker

The double tracker folder name might look redundant, but it's a Django convention called template namespacing. It prevents naming conflicts if you have multiple apps with templates that share the same filename.

7.2 How to Create the Workout List Template

Create a file called tracker/templates/tracker/workout_list.html and add the following code:




    
    
    My Workouts
    



    
        My Workouts
        + Log a Workout
        {% if workouts %}
            {% for workout in workouts %}
                
                    
                        {{ workout.activity }}
                        {{ workout.duration }} minutes
                    
                    {{ workout.date }}
                
            {% endfor %}

        {% else %}
            
                No workouts logged yet. Start by adding one!
            
        {% endif %}

There are a few things worth noting here:

If you look closely at the HTML, you'll spot some weird-looking tags wrapped in curly braces ( {% %} and {{ }} ). Think of them as special instructions for Django.

You use the double curly braces ({{ }}) when you want to output or display a piece of data directly on the page.

On the other hand, you use the brace-and-percent-sign combo ( {% %} ) when you need Django to actually perform an action or apply logic, like running a loop or checking a condition.

They allow us to inject dynamic data straight from our Python backend right into our otherwise static HTML.

Lets look at this code snippet for the workout_list.html


    
        My Workouts
        + Log a Workout
        {% if workouts %}
            {% for workout in workouts %}
                
                    
                        {{ workout.activity }}
                        {{ workout.duration }} minutes
                    
                    {{ workout.date }}
                
            {% endfor %}

        {% else %}
            
                No workouts logged yet. Start by adding one!
            
        {% endif %}

There are a few things worth noting here.

Right under the main heading, you'll see this line:

Instead of hardcoding a web link like href="/add-workout/", Django uses the {% url %} tag to generate the link dynamically. You pass it the name of the route (in this case, add_workout), and Django automatically figures out the correct URL path.

If you ever change the URL structure in your Python code later, Django updates this link automatically. You never have to hunt through HTML files to fix broken links!

The {% if workouts %} block checks whether there are any workouts to display. If the list is empty, it shows a friendly message instead of a blank page.

The {% for workout in workouts %} loop iterates over every workout in the list and renders a card for each one. The double curly braces {{ workout.activity }} insert the value of each field into the HTML

Inside the loop, you'll notice tags that look like this:

{{ workout.activity }}
{{ workout.duration }}
{{ workout.date }}

As Django loops through each workout object, it uses dot notation to peek inside that specific object and grab its details. It grabs the activity type (like "Running"), the duration ("30"), and the date ("March 30"), and prints that exact text directly onto the webpage for the user to see.

7.3 How to Create Add Workout Template

Create a file called tracker/templates/tracker/add_workout.html and add the following code:




    
    
    Log a Workout
    


    
       Log a Workout
        
            {% csrf_token %}
            
                Activity
                {{ form.activity }}
                {% if form.activity.errors %}
                    {{ form.activity.errors }}
                {% endif %}
            
            
                Duration (minutes)
                {{ form.duration }}
                {% if form.duration.errors %}
                    {{ form.duration.errors }}
                {% endif %}
            

            
                Date
                {{ form.date }}
                {% if form.date.errors %}
                    {{ form.date.errors }}
                {% endif %}
            

            
                
                Cancel

In the previous template, we learned how to display data. Now, we're looking at a form that actually collects data. Handling forms manually in web development can get messy, but Django provides some powerful template tags to do the heavy lifting for us.

Let's look at the Django-specific logic powering this form:

First, right after opening the

tag, you'll spot a very important line: {% csrf_token %}. Whenever you submit data to a server using a "POST" method, malicious sites can potentially intercept or forge that request.

By including this {% csrf_token %}, you tell Django to generate a unique, hidden security key for the form. When the user clicks "Save Workout," Django checks this token to guarantee the request is legitimate. If you forget this tag, Django will simply reject your form!


            {% csrf_token %}
            
                Activity
                {{ form.activity }}
                {% if form.activity.errors %}
                    {{ form.activity.errors }}
                {% endif %}
            
            
                Duration (minutes)
                {{ form.duration }}
                {% if form.duration.errors %}
                    {{ form.duration.errors }}
                {% endif %}
            

            
                Date
                {{ form.date }}
                {% if form.date.errors %}
                    {{ form.date.errors }}
                {% endif %}
            

            
                
                Cancel

Now let's talk about automatically generating the form fields. Instead of manually typing out all the HTML tags for the activity, duration, and date, we let Django do it for us using display tags ({{ }}).

Each {{ form.activity }}, {{ form.duration }}, and {{ form.date }} tag renders the corresponding form input. Django handles the HTML attributes, input types, and validation for you based on the model and form definitions.

The error blocks below each field display validation messages if a user submits invalid data, like entering text in the duration field instead of a number. Users make mistakes. They might leave a required field blank or type text into a number field. Fortunately, Django validates the data for you and sends back errors if something goes wrong.

Underneath each input field, we use a logic block that looks like this:
{% if form.activity.errors %}

This code checks a simple condition: Did the user mess up this specific field? If Django found an error with the "activity" input, the code drops into the if block and uses{{ form.activity.errors }} block to print the exact error message (like "This field is required") right below the input box.

You may notice that both templates include inline CSS rather than a separate stylesheet. For a small project like this, inline styles keep things simple and self-contained. In a larger project, you would use Django's static files system to manage CSS separately.

Step 8: How to Connect URLs

You have views and templates, but Django doesn't know when to use them yet. You need to map URLs to views so that visiting a specific address in the browser triggers the right view function.

8.1 How to Create App Level URLs

Create a new file called tracker/urls.py and add the following code:

from django.urls import path
from . import views

urlpatterns = [ 
    path('', views.workout_list, name='workout_list'), 
    path('add/', views.add_workout, name='add_workout'), 
]

Each path function takes three arguments.

The first is the route string that represents a URL pattern (an empty string means the root of the app).

The second is the view function to call when that URL is visited.

The third is a name you can use to reference this URL elsewhere in your code, like in the {% url %} template tags you used earlier.

8.2 How to Link App URLs to project

Now that your app-level URLs are set up, the next step is to connect them to the main project so Django knows where to start routing requests. Think of it like linking a smaller map (your app) to a bigger map (your project), so everything works together smoothly.

Open fitness_project.urls.py and update it to include your app's URLs:

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('tracker.urls')),
]

The include() function tells Django to look at the URL patterns defined in the tracker/urls.py file whenever someone visits your site. The empty string prefix means your tracker app handles requests at the root of the site.

Here's the full picture of how a request flows through the URL system.

When someone visits http://127.0.0.1:8000/add/, Django first checks fitness_project/urls.py. It matches the empty prefix and delegates to tracker/urls.py. There, it matches add/ and calls the add_workout view.

Step 9: How to Test the Application Locally

At this point, your app has everything it needs to work. Let's test it.

Start the development server by running the command:

python manage.py runserver

Open your browser and visit http://127.0.0.1:8000/. You should see the workout list page with the heading "My Workouts" and a button that says "+ Log a Workout."

Click that button. You should see the workout form with fields for activity, duration, and date.

Fill in some test data:

Activity: Skipping
Duration: 25
Date: Pick today's date from the date picker

Click "Save Workout" You should be redirected back to the workout list page, and your new workout should appear as a card.

Try adding a few more workouts with different activities and dates. Make sure they all show up on the list page in the correct order (most recent first).

This is also a good time to experiment. Try submitting the form with missing fields and see how Django handles validation.

Try accessing the admin panel at http://127.0.0.1:8000/admin/ to see your workouts there as well.

If everything works as expected, you're ready to put your app on the internet.

Step 10: How to Prepare for Deployment

Running your app on localhost is great for development, but nobody else can see it. Deployment means putting your app on a server that's accessible from anywhere on the internet.

Before you deploy, you'll need to make a few changes to your project's settings.

10.1 How to Update Settings for Production

Open fitness_project/settings.py and make the following changes.

First, set DEBUG to False.

During development, DEBUG = True shows detailed error pages that help you fix problems. In production, these error pages would expose sensitive information about your code and server to anyone who triggers an error.

Next, update ALLOWED_HOSTS to include PythonAnywhere's domain.

This setting tells Django which domain names are allowed to serve your app. Replace yourusername with the actual PythonAnywhere username you will create in the next step.

ALLOWED_HOSTS = ['yourusername.pythonanywhere.com']

Finally, add a STATIC_ROOT setting so Django knows where to collect your static files (CSS, JavaScript, images) for production:

import os
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')

These are the minimum changes needed for a basic deployment.

💡 For a production app handling real user data, you would also want to set a secure SECRET_KEY, configure a proper database like PostgreSQL, and set up HTTPS. But for a learning project, these changes are enough.

Step 11: How to Deploy Your Django App on PythonAnywhere

PythonAnywhere is a hosting platform designed specifically for Python web applications. It offers a free tier that's perfect for beginner projects, and it handles much of the server configuration that would otherwise be complex to set up on your own.

11.1 How to Create a PythonAnywhere Account

Go to pythonanywhere.com and sign up for a free "Beginner" account. Remember the username you choose, because your app will be available at yourusername.pythonanywhere.com.

Now signup to the website. Fill in the username, email and password and click on the free tier or now.

11.2 How to Upload Your Project Files

After logging in, you have two options for getting your project files onto PythonAnywhere.

Option A: Upload using Git

If your project is in a Git repository, open a Bash console from the PythonAnywhere dashboard by clicking "Consoles" and then "Bash." Then clone your repository:

git clone https://github.com/yourusername/fitness-tracker.git

In this tutorial, we won't be using Git. Instead we'll follow the second option.

Option B: Upload files manually

First go your project folder in your computer and created a compressed version of the project.

IMPORTANT NOTE: When you create the compressed file, make sure to first create a copy of the project somewhere and remove the venv and pycache folder before you compress it.

Navigate to your home directory and click on upload file tab and upload the compressed file.

Now we need to unzip the compressed file. To do this, go to the Consoles tab and click on Bash console.

The bash console should open. Then type the following command in the console to unzip the folder:

unzip fitness-tracker.zip

11.3 How to Set Up a Virtual Environment in PythonAnywhere

Open a Bash console from the PythonAnywhere dashboard. Navigate to your project directory and create a fresh virtual environment:

cd fitness-tracker

Type the following command to install a virtual environment as we've done before and then activate the virtual environment:

python3 -m venv venv

source venv/bin/activate

Now install Django as before using pip install django command:

11.4 How to Run Migrations and Create a SuperUser on PythonAnywhere

While you're still in the Bash console with your virtual environment activated, run the migrations to create the database tables on the server:

python manage.py makemigrations

python manage.py migrate

python manage.py createsuperuser

11.4 How to Configure the Web App in Pythonanywhere

Go to the "Web" tab on the PythonAnywhere dashboard and click "Add a new web app." Follow the setup wizard:

Click "Next" on the domain name step (remember the free tier uses yourusername.pythonanywhere.com).

Select "Manual configuration" (not "Django" – the manual option gives you more control).

Then choose the Python version that matches what you installed. In my case it's 3.13, so I'll choose 3.13

Click on Next button and a WSGI (Web Server Gateway Interface) will be created.

With this we've created the web app:

After you've set up the web app, you have to do two more things:

Set the virtual environment path
Configure the WSGI file

11.5 How to Set the Virtual Environment Path

On the Web tab, scroll down to the "Virtualenv" section and enter the path to your virtual enviroment. The path to the file should be like this:

/home/yourusername/fitness-tracker/venv

11.6 How to Configure the WSGI file

Still on the Web tab, scroll to the code section and click on the WSGI configuration file link:

Delete all the contents and replace them with the content below and save the file:

import os
import sys
path = '/home/prabodhtuladhardev/fitness-tracker' #replace with your username
if path not in sys.path:
    sys.path.append(path)

os.environ['DJANGO_SETTINGS_MODULE'] = 'fitness_project.settings'

from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()

11.7 How to Set Up Static Files

Still on the "Web" tab, scroll down to the "Static files" section. Add an entry:

URL: /static/
Directory: /home/yourusername/fitness-tracker/staticfiles

Then go back to your Bash console and run the following command:

python manage.py collectstatic

This copies all static files to the staticfiles directory so PythonAnywhere can serve them directly.

Go back to the "Web" tab and click the green "Reload" button at the top. This restarts your app with all the new configuration.

11.8 How to View Your Live Application

Open a new browser tab and visit https://yourusername.pythonanywhere.com. You should see your fitness tracker, live on the internet.

Try adding a workout.

Visit the admin panel at https://yourusername.pythonanywhere.com/admin/.

Everything should work just as it did on your local machine, but now anyone with the link can access it.

This is a meaningful milestone. You've gone from zero to a deployed Django application. Share the link with a friend or post it in a coding community. Seeing your work live on the internet is one of the most motivating experiences in learning to code.

Common Mistakes and How to Fix Them

Even when you follow each step carefully, things can go wrong. Here are the most common issues beginners run into and how to solve them.

"ModuleNotFoundError: No module named 'django'" – This usually means your virtual environment isn't activated. Run source venv/bin/activate (macOS/Linux) or venv\Scripts\activate (Windows) and try again. On PythonAnywhere, make sure the virtualenv path in the "Web" tab points to the correct location.

"DisallowedHost" error – You forgot to add your domain to ALLOWED_HOSTS in settings.py, or there's a typo. Double-check that it matches your PythonAnywhere URL exactly.

Static files not loading in production – Make sure you ran python manage.py collectstatic and that the static file mapping on PythonAnywhere points to the correct staticfiles directory. Also verify that STATIC_ROOT is set in settings.py.

"No such table" or migration errors – You probably forgot to run python manage.py migrate after cloning or uploading your project to PythonAnywhere. Run the migrate command in the Bash console.

Changes not showing up on PythonAnywhere – After making any code changes, you must click the "Reload" button on the "Web" tab. PythonAnywhere does not automatically detect file changes.

How You Can Improve This Project

The fitness tracker you built is intentionally simple. That's a feature, not a limitation. A working simple project is the perfect foundation for learning more.

Here are some ideas for expanding it.

Add user authentication: Right now, anyone who visits the site sees the same workout data. Django has a built-in authentication system that lets you add registration, login, and logout. Each user could then have their own private list of workouts.
Add the ability to edit and delete workouts. Currently, once a workout is saved, there's no way to change or remove it from the interface (you can do it through the admin panel, but not the main app). Try creating new views and templates for editing and deleting.
Add workout categories or tags. Let users categorize their workouts as "Cardio," "Strength," "Flexibility," and so on. This would involve adding a new field to the model or creating a separate Category model with a foreign key relationship.
Add charts and progress tracking. Use a JavaScript charting library like Chart.js to display workout trends over time. For example, you could show a bar chart of total minutes exercised per week.
Build an API with Django REST Framework. If you want to learn about building APIs, try installing Django REST Framework (DRF) and creating API endpoints for your workouts. This would let you build a mobile app or a separate front end that communicates with your Django back end.

Each of these improvements will teach you something new about Django while building on the foundation you already have.

Conclusion

You've built a fully functional fitness tracker web app with Django and deployed it to the internet. That's no small achievement.

Along the way, you learned how Django projects and apps are structured, how models define the shape of your data, how migrations translate those models into database tables, how views handle the logic of your application, how templates render dynamic HTML, and how URLs tie everything together. You also went through the entire deployment process on PythonAnywhere.

These are the core building blocks of Django development. The patterns you practiced here – defining a model, creating a form, writing a view, building a template, and connecting a URL – are the same patterns you will use in every Django project, no matter how complex.

The best way to solidify what you have learned is to keep building. Try one of the improvements mentioned above, or start a completely new project. A calorie tracker, a habit tracker, an expense tracker, or a personal journal would all use the same Django concepts with slightly different models and views.

Prabodh Tuladhar - freeCodeCamp.org

How to Build a Scoped Note-Taking API with Django Rest Framework and SimpleJWT

What We'll Cover:

Prerequisities

What is JWT and Why Use It Over Session Authentication?

How Session Authentication Work

How JWT Authentication Works

Step 1: How to Set Up the Project and Install the Dependecies

1.1 How to Create the Project

1.2 How to Create a Virtual Environment and Install the Required Dependencies

1.3 How to Create the Project and the App

1.4 How to Register the App and Django Rest Framework (DRF)

Step 2: How to Create a Custom User Model

2.1 How to Define the Custom User Model

2.2 How to Tell Django to Use Your Custom User Model

2.3 How to Run Migrations

Step 3: How to Define the Note Model

3.2 How to Apply Migration

3.3 How to Register Models in the Admin

Step 4: How to Create the Serializer

4.1 How to Create UserSerializer

4.2 How to Create NoteSerializer

Step 5: How to Configure SimpleJWT

5.1 How to Update REST Framework Settings

5.2 How to Add Token URL Endpoints

Step 6: How to Build the Authentication Logic

Step 7: How to Implement Scoped Views

7.1 How to Create a NoteViewSet

7.2 Why This Matters: Preventing ID Enumeration Attacks

Step 8: How to Connect a URL

8.1 How to Create App-level URLs

8.2 How to Verify the Project-Level URLs

Step 9: How to Test the APIs with Postman

9.1 How to Register a User

9.2 How to Obtain Access and Refresh Tokens

9.3 How to Create a Note

9.4 How to List Your Notes

9.5 How to Demonstrate Scoping

Step 10: How to Handle Token Expiration with Refresh Tokens

How You Can Improve This Project

Conclusion

How to Build and Deploy a Fitness Tracker Using Python Django and PythonAnywhere - A Beginner Friendly Guide

Table of Contents

Prerequisites

What You Are Going Build

Step 1: How to Set Up Your Django Project

1. 1 How to Create a Virtual Environment

1.2 How to Install Django

1.3 How to Create the Project

1.4 How to Run the Development Server

Step 2: How to Create a Django App

2.1 How to Generate the App

2.2 How to Register the App

Step 3: How to Create a Workout Model

3.1 How to Define the Model

Step 4: How to Apply Migrations

4.1 How to Generate the Migration

4.2 How to Apply the Migration

Step 5: How to Register the Model in the Admin Panel

5.1 How to Add Model to Admin

5.2 How to Create a Superuser

5.3 How to Access the Admin Panel

Step 6: How to Create Views for the App

6.1 How to Create a Form Class

6.2 How to Write Views

Step 7: How to Create Templates

7.1 How to Set Up the Template Directory

7.2 How to Create the Workout List Template

My Workouts

My Workouts

7.3 How to Create Add Workout Template

Log a Workout

Step 8: How to Connect URLs

8.1 How to Create App Level URLs

8.2 How to Link App URLs to project

Step 9: How to Test the Application Locally

Step 10: How to Prepare for Deployment

10.1 How to Update Settings for Production

Step 11: How to Deploy Your Django App on PythonAnywhere

11.1 How to Create a PythonAnywhere Account