Forem: kihuni

My Journey Contributing to Django: From Intimidation to a Merged Ticket 🚀

kihuni — Mon, 22 Dec 2025 08:46:57 +0000

Contributing to Django felt intimidating at first.

This isn’t just any open-source project. Django powers millions of applications worldwide. The codebase is massive, the standards are high, and every change goes through careful review. As someone still growing as a backend engineer, I often wondered:

Am I really ready to contribute here?

Spoiler: You don’t need to feel ready; you just need the right environment, guidance, and consistency. That environment, for me, was Djangonaut Space.

Djangonaut Space

Djangonaut Space is more than a mentorship program; it’s a launchpad into real-world open source. It pairs contributors with experienced navigators and captains who help you move from "I want to contribute" to "my code is live in Django."

Through the program, I learned:

How to read and understand Django’s internals
How to navigate tickets, discussions, and code reviews
How to communicate clearly with maintainers
How to accept feedback without ego, and improve fast
Most importantly, I learned that open source is collaborative, not competitive.

The Ticket That Changed Everything

My contribution focused on improving argparse error handling in Django management commands, a small but meaningful enhancement that improves developer experience.

At first, the problem looked simple. But as with most Django work, the real challenge wasn’t writing code, it was:

Understanding existing behavior
Making changes without breaking backwards compatibility
Writing code that aligns with Django’s philosophy
Justifying decisions clearly during review

The review process taught me a lot:

My code was reviewed line by line
I rebased multiple times
I received suggestions that genuinely improved the implementation
I learned when to push back and when to listen

And then it happened.

🎉 The ticket was merged into Django’s main branch.

Seeing that merge wasn’t just exciting, it was validating. It confirmed that with the right mentorship and persistence, contributing to major open-source projects is absolutely achievable.

What This Journey Taught Me

This experience reshaped how I think about open source and software engineering in general.

Here are a few lessons I’m carrying forward:

You don’t need to know everything to contribute
Good questions are as valuable as good code
Feedback is a gift, even when it’s tough
Consistency beats confidence
Community accelerates growth

Open source isn’t about being perfect. It’s about showing up, learning in public, and improving with every iteration.

If you’re a developer sitting on the fence, wondering whether you’re good enough to contribute to a large project like Django, this is your sign.

Start small. Ask questions. Join a mentorship program if you can. And don’t underestimate the impact of one well-reviewed contribution. That one ticket might just change how you see yourself as a developer.

🙏 Acknowledgements & Thanks

This journey wouldn’t have been possible without the incredible people behind the Djangonaut Space team Mars.

Navigator: @lilian — thank you for the guidance, structure, and encouragement throughout the journey.

Captain: @sean — thank you for the thoughtful reviews, patience, and for the encourangement.

Djangonauts:
@eddy,** @rim Choi**, thank you for the collaboration, discussions, and shared learning. Building alongside you made the experience even better.

And to the wider Django community, thank you for maintaining such a welcoming and high-quality open-source ecosystem.

Learn URLs in Django: From Setup to Dynamic Routing

kihuni — Sat, 27 Sep 2025 02:04:16 +0000

In our previous blog, how the Web Talks to Django, we saw how Django handles requests and responses internally. Now that you have a clear picture of what happens when a user types a web address and hits enter, it’s time to take the next step: building that bridge between the browser and your Django code.

In this blog, we’ll focus on Django’s URL system, the backbone of how requests find their way to the right view(" a chunk of Python code"). We will explore more about **views **later.

You’ll learn how to set up a Django project, declare URLs, organize them into logical groups, and even extract useful information directly from the URL to use in your views.

Getting Django Set Up

We’ll walk step by step through setting up your first Django project and running it locally.

Django runs on Python, so the first step is to make sure you have it installed. Run:

python --version

If not installed, visit python and follow instructions to install Python.

Then, we need a place to put our work. You can name your project the name you prefer. I am going to use "mastering-django".

mkdir mastering-django
cd mastering-django

Next, we install Django into a virtual environment so we keep our project dependencies separate from the rest of the installed Python packages on our machine.

python3 -m venv venv

Activate it:
source venv/bin/activate

With your environment active, install Django:

(venv) $ pip install Django

Django comes with some tools that we can use to get a project started quickly. let’s start a new Django project:

(venv) $ django-admin startproject myproject .

When you run django-admin startproject myproject ., Django creates a project structure for you. It might look like a lot at first, but each file has a clear purpose. Let’s walk through them.

    manage.py
    myproject/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py

manage.py

This is your project’s remote control. It’s a command-line tool that lets you:

Start the development server
Apply database migrations
Create apps
Manage users (like creating a superuser)

Whenever you interact with your project, you’ll usually do it through manage.py.

The Inner myproject/ Folder

This folder holds your project’s configuration files.

init.py
Marks the folder as a Python package. It’s usually empty, but it tells Python “this is code you can import.”
settings.py
The brain of your project. It stores all configurations — installed apps, database setup, middleware, templates, static files, and more.
urls.py
The map of your project. It connects browser requests (like /about/ or /blog/) to the right views in your code.
asgi.py
Entry point for ASGI servers. It allows Django to support modern features like WebSockets and async handling.
wsgi.py
Entry point for WSGI servers. This is what most traditional web servers (like Gunicorn or uWSGI) use to run Django apps in production.

By understanding these files, you know where your configurations live and how Django connects the dots.

Next, let’s run the development server to make sure everything is working correctly:

(venv) $ python manage.py runserver

If you open http://127.0.0.1:8000/ in your browser, you’ll see Django’s welcome page 🎉. That means your project is alive and ready

Now that our project is running and we understand its structure. Now it’s time to focus on one of the most important pieces: urls.py.

URL configuration in Django

Every time you type a URL into your browser and hit Enter, Django needs to know: where should this request go?

That’s where urls.py configuration comes in. Think of Django’s URL configuration (urls.py) as a list of paths. Whenever a request comes in, Django scans that list from top to bottom. As soon as it finds a match, it stops searching and routes the request to the matching view (note: a view is just a chunk of Python code that returns a response; we’ll dive into views in the next blog).

Here’s a simple example of a url.py:

# myproject/urls.py
from django.urls import path
from application import views

urlpatterns = [
    path("", views.home),
    path("about/", views.about),
    path("contact/", views.contact),
    path("terms/", views.terms),
]

If you visit https://www.example.com/about/, Django trims off the domain and leading slash, leaving just about/. That matches the second entry above, so the request is sent to views.about.

And if you simply visit the root URL https://www.example.com/, Django matches the empty string " " and sends the request to views.home.

The order matters. If you accidentally define two paths that could match the same URL, Django will always go with the first one it finds and ignore the rest.

Notice the trailing slash (/). By default, Django expects URLs to end with one. If you type https://www.example.com/about (without the slash), Django will redirect you to the correct version because of the APPEND_SLASH default setting.

Dynamic Paths with Converters

Static paths like /about/ are nice, but most real-world apps need to be flexible. Imagine if every blog post had to live at /blog/ with no way of telling them apart, that wouldn’t work.

Instead, we usually want URLs to carry information. For example:

A blog post URL might include a year and a slug, like /blog/2024/django-rocks/.
A user profile URL should work for any username, like /users/stephen/.

That’s where path converters come in. They let you pull pieces of information straight out of the URL and hand them directly to your view.

# myproject/urls.py
from django.urls import path
from application import views

urlpatterns = [
    path("blog/<int:year>/", views.blog_by_year),
    path("users/<str:username>/", views.profile),
]

Here’s what happens behind the scenes:

If someone visits /blog/2024/, Django sees int:year and automatically captures 2024 as an integer. That value is then passed into views.blog_by_year(year=2024).
If someone visits /users/stephen/, Django captures "stephen" as a string and hands it to your view: views.profile(username="stephen").

The best part? Django validates the values before they ever hit your code. If a user tries /blog/notayear/, Django knows that “notayear” is not an integer, so it returns a clean 404 Not Found without bothering your view.

In other words:

You get dynamic, flexible URLs.
You don’t need to write messy validation logic in your views.
Your app stays both user-friendly and safe.

Think of converters as Django’s built-in parsers for your URLs. They keep your code clean while giving you the power to make URLs that feel natural and meaningful.

Regular Expression Paths

Sometimes, path converters aren’t enough. Let’s say you only want to match a four-digit year, such as 2025. In that case, you can reach for re_path and use a regular expression (regex).

from django.urls import re_path
from application import views

urlpatterns = [
    re_path(r"^blog/(?P<year>[0-9]{4})/(?P<slug>[\w-]+)/$", views.blog_post),
]

At first glance, regex looks intimidating, but here’s what’s happening:

(?P[0-9]{4}) - captures exactly four digits and passes them as a variable called year.
(?P[\w-]+) - captures a word-like slug (letters, numbers, underscores, or dashes).

So if someone visits /blog/2025/django-rocks/, Django will match it and call:

views.blog_post(year=2025, slug="django-rocks")

Regex is powerful, like a chainsaw. You can cut through particular patterns, but you don’t always need it. Most of the time, Django’s simple path converters (int, str, slug, etc.) are more than enough.

Grouping Related URLs

As your project grows, dumping all routes into one urls.py file can get messy. Instead, Django encourages you to let each app manage its own URLs and then connect them in the main project.

For example, suppose you have two apps: schools and students.

myproject/urls.py

from django.urls import path, include

urlpatterns = [
    path("schools/", include("schools.urls")),
    path("students/", include("students.urls")),
]

school.url

from django.urls import path
from . import views

urlpatterns = [
    path("", views.index),
    path("<int:school_id>/", views.school_detail),
]

students.urls

from django.urls import path
from . import views

urlpatterns = [
    path("", views.index),
    path("<int:student_id>/", views.student_detail),
]

Now, each app is responsible for its own routing, and the main project needs to know where to plug things in. This makes your project cleaner, modular, and much easier to maintain.

Naming URLs

Hardcoding URLs everywhere in your project is risky. Imagine you define a route at /blog/categories/, but later decide to move it to /marketing/blog/categories/. If you’ve hardcoded links, you’d need to hunt down and update every single one.

Instead, Django lets you name your URLs.

# project/urls.py
from django.urls import path
from blog import views

urlpatterns = [
    path("marketing/blog/categories/", views.categories, name="blog_categories"),
]

Now you can reference this route by name instead of by path.

Example in a view:

from django.http import HttpResponseRedirect
from django.urls import reverse

def old_blog_categories(request):
    return HttpResponseRedirect(reverse("blog_categories"))

Even if the path changes later, as long as the name (blog_categories) stays the same, your code keeps working.

For larger projects, you can even use namespaces (like schools:index vs. students:index) to avoid naming conflicts.

Wrapping Up

And that’s a full tour of Django’s URL system! 🎉

Here’s what we covered:

How Django matches requests against urlpatterns.
Why the order of your routes matters.
How to use path converters to capture values from the URL.
When to reach for re_path and regex for advanced matching.
How to group URLs by app using include().
How naming (and namespacing) URLs makes your project more flexible.

URLs are the map of your Django project. They decide how a user’s request finds its way to the right piece of code. Once you understand this mapping system, everything else in Django starts to click into place.

In the next blog, we’ll zoom in on the views, those chunks of Python code that actually generate the response. That’s where we’ll really bring our URLs to life. 🚀

The Big Picture

Here’s the request flow at a glance:

Browser – the user types in a URL and hits enter.
Django URLconf (urls.py) – Django looks through your list of paths to find a match.
View – the matching view (Python function or class) runs and decides what to return.
Response – Django sends the result (HTML, JSON, redirect, etc.) back to the browser.

How the Web Talks to Django: A Beginner's Guide

kihuni — Sun, 14 Sep 2025 11:03:54 +0000

Learn how your keystrokes in the browser turn into responses from Django.

Imagine you open your browser, type www.example.com, and within a blink, a fully loaded page appears. Feels like magic, right? But behind that magic is a chain of events quietly working together to make it possible.

Django calls itself a web framework, but unless you know how the web itself works, that phrase can feel like jargon. So before we talk about Django, let’s peel back the curtain on how the web actually delivers that page to your screen.

Think of it like sending a letter. You write the address on the envelope, drop it in the mailbox, and somehow, almost instantly, it arrives at the right house. The internet works in a very similar way.

In this article, I’m going to walk you through the journey of a request:

How a browser knows where to go.
How the internet finds the right server.
How your request gets translated into something a web app (like Django) can understand.
And finally, how Django receives the request, does the necessary work, and sends a response back.

By the end, you’ll see exactly how the web and Django talk to each other, from your first keystroke in the browser bar to Django sending back the page you see.

How the Web Works

When you hit Enter in your browser to visit www.example.com, a whole chain of events kicks off. Tiny, invisible steps (happening in milliseconds) connect you to the right server, fetch the right information, and display it neatly on your screen.

To understand how a request reaches a server, we’ll focus on two major steps:

DNS (Domain Name System)
HTTP (Hypertext Transfer Protocol)

What is DNS (Domain Name System)?

Every computer connected to the internet can be reached using a network number called an IP address. Maybe you’ve seen some of these before:

127.0.0.1 — the address your computer uses for itself (on its internal network).
192.0.2.172 — an example of a public IP address that makes a computer reachable on the internet.

Computers love numbers. But for humans? Remembering long strings of numbers is not fun. That’s where the Domain Name System (DNS) comes in.

DNS is like the Internet’s phonebook. When you type a website address (like example.com) into your browser, DNS translates that human-friendly name into the actual IP address of the server hosting the site.

The Structure of Domain Names

A domain name has a simple structure, made of several parts separated by dots and read from right to left.

Take our example: www.example.com

.com → This is the Top-Level Domain (TLD). TLDs are carefully managed by an organization called ICANN. You’ve probably also seen others like .org, .net, .dev, or country codes like .ke (Kenya) or .uk (United Kingdom).
example → This is the domain name. It’s the unique identity of a service on the internet, the part users are most likely to recognize.
www → This considered the subdomain of a domain. A domain might have many of these, like www, m, mail, wiki, or whatever a domain owner might want to name them. Subdomains can also be more than one level deep, so a.b.example.com is valid, and a is a subdomain of b.example.com and b is a subdomain of example.com.

So far, we’ve seen how the internet uses DNS like a massive phonebook (or a global postal system) to turn human-friendly addresses like example.com into the exact IP address of the server you want to reach. Without DNS, you’d be stuck memorizing numbers instead of names, and the web would feel a lot less human.

But finding the right server is just the beginning. Once your browser knows where to go, the next big question is: how do the browser and server actually talk to each other? That’s where HTTP comes in the language of the web.

Next, we’ll follow the request a little further and see how your browser and Django exchange messages, step by step.

HTTP — The Language of the Web

We saw how DNS acts like the internet’s phonebook, helping your browser find the exact server behind a domain name. But once your browser has the server’s address, another question pops up:

How do the browser and server actually talk to each other?

That’s where HTTP (Hypertext Transfer Protocol) comes in. If DNS is the postal system that makes sure your letter reaches the right house, HTTP is the language you and the house’s owner use when you start a conversation at the door.

What is HTTP?

HTTP is the protocol of communication between browsers (clients) and servers. It defines the rules for:

How a request should be written.
How a server should respond.
What happens if something goes wrong?

Every time you visit a website, your browser is quietly saying something like:

“Hey server, I’d like the homepage, please.”

And the server responds:

“Here you go, HTML, CSS, images, and everything you need to display the page.”

This back-and-forth happens in milliseconds, but it’s the foundation of how the web works.

The Anatomy of an HTTP Request

When your browser asks for a page, it doesn’t just shout “give me stuff!” The request is structured, like a well-written letter. It usually has three main parts:

Request Line Example: GET /about/ HTTP/1.1

This tells the server what you want (GET means “fetch something,” /about/ means a path to a particular resource on a site).

Headers

Think of these as little notes with extra info.

Example: User-Agent: Chrome/120 (so the server knows the type of browser making the request).

Body (sometimes)

For requests such as submitting a form, the actual data (e.g., your username/password) should be entered here.

The Anatomy of an HTTP Response

Once the server understands your request, it replies with a structured response. Again, three main parts:

Status Line

Example: 200 OK → Everything went fine.

Or 404 Not Found → Page doesn’t exist.

Or 500 Internal Server Error → Something broke on the server side.

Headers

Extra info for the browser, like how long to cache the response or what type of file it is.

Body

This is the actual content, HTML, JSON, an image, or whatever the browser asked for.

When the Request Finally Reaches Django

Alright, we’ve talked about browsers, DNS, and HTTP. We know how a request leaves the browser, finds the right server, and arrives at its destination.

Now the spotlight is on Django. This is where the real action begins. Django’s job is simple at first glance: take an incoming HTTP request and return an HTTP response.

That response could be a web page, JSON data for an API, or even a file download. But before Django can step in, there’s one last hurdle to clear: the Python web server.

The Python Web Server

When people say “web server,” they might mean two things:

the machine running the software, or
the software itself that listens for requests.

Here, we’re talking about the software.

The web server is the first piece of software to actually *hear * the HTTP request when it arrives at the server. Its job is to pass that raw HTTP request into a format Django can understand.

In Python, there is a format called WSGI (Web Server Gateway Interface). WSGI is used so that any web server(Gunicorn, uWSGI, or mod_wsgi) can speak to any Python web framework. Without Python's standard WSGI, every web server would need a custom way of talking to every framework.

Once the request is handed off by the server through WSGI, Django steps in. This is where your work as a Django developer really matters.

Your job is to:

Tell Django which URLs it should listen for.
Write the views that decide what happens when those URLs are requested.

From there, Django builds the response, whether that’s rendering an HTML template, returning JSON data, or redirecting the user somewhere else.

We’ve followed the path of a request all the way from your browser to Django — through DNS, HTTP, the web server, and finally into Django itself. Along the way, we’ve seen how the internet acts like a massive postal system and how Django steps in to make sense of those requests and send back the right response.

Now that you understand how the web and Django talk to each other, you’re ready to dive deeper into Django itself. In the next post, we’ll roll up our sleeves and explore how to:

set up a Django project,
declare URLs,
group related URLs, and
extract information from URLs to power your views.

Think of today’s post as the map, and the next one as the actual journey inside Django’s world.

How to Send Emails with Django: A Simple Guide

kihuni — Sat, 02 Aug 2025 08:30:27 +0000

Sending emails in Django is straightforward, thanks to its built-in email functionality. Whether you're notifying users, sending password resets, or automating communications, Django's send_mail function makes it easy to do so. In this guide, we'll walk through the process of setting up and sending emails in Django, then demonstrate how to test it using the Django shell.

Who Should Read This?

Developers who are already familiar with Django. This is not for absolute beginners, as it assumes familiarity with Django project structure and basic configuration.

Configure Email Settings in Django

To send emails with Django, you need to have a local Simple Mail Transfer Protocol (SMTP) server, or you need to access an external SMTP server, like your email service provider.

The following settings allow you to define the SMTP configuration to send emails with Django:

EMAIL_HOST: The SMTP server host; the default is localhost
EMAIL_PORT: The SMTP port; the default is 25
EMAIL_HOST_USER: The username for the SMTP server
EMAIL_HOST_PASSWORD: The password for the SMTP server
EMAIL_USE_TLS: Whether to use a Transport Layer Security (TLS) secure connection
EMAIL_USE_SSL: Whether to use an implicit TLS secure connection

For this blog, we will use Google's SMTP server. If you have a Gmail account, edit the settings.py file of your project and add the following code:

# Email server configuration
EMAIL_HOST = 'smtp.gmail.com'
EMAIL_HOST_USER = 'your_account@gmail.com'
EMAIL_HOST_PASSWORD = ''
EMAIL_PORT = 587
EMAIL_USE_TLS = True

Replace your_account@gmail.com with your actual Gmail account.

N/b If you can’t use an SMTP server, you can tell Django to write emails to the console by adding the following settings to the settings.py file:

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

Steps to Configure Gmail SMTP

Gmail requires secure settings and an App Password for authentication. Google allows you to create app-specific passwords for your account. An app password is a 16-digit passcode that grants less secure apps or devices permission to access your Google account.

Open https://myaccount.google.com/ in your browser. On the left menu, click on Security. You will See the following screen:

Click on the 2-Step Verification. When you click 2-step verification, you will see the following screen:

Click on 'app passwords,' enter a name for your app, and then click 'Create.'

A new password will be generated like this:

Copy the generated app password.

Edit the settings.py file of your project and add the app password to the EMAIL_HOST_PASSWORD setting, as follows:

# Email server configuration
EMAIL_HOST = 'smtp.gmail.com'
EMAIL_HOST_USER = 'your_account@gmail.com'
EMAIL_HOST_PASSWORD = 'xxxxxxxxxxxxxxxx'
EMAIL_PORT = 587
EMAIL_USE_TLS = True

Open the Python shell by running the following command:

python manage.py shell

Run the following code in the python shell:

Python 3.12.3 (main, Jun 18 2025, 17:59:45) [GCC 13.3.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from django.core.mail import send_mail
>>> send_mail('Django mail', 'Hey there, i hope this email finds you well', 'stephenkihuni55@gmail.com',
... ['stephenkihuni55@gmail.com'], fail_silently=False)

The send_mail() function takes the subject, message, sender, and list of recipients as required arguments. By setting the optional argument fail_silently=False, we are telling it to raise an exception if the email cannot be sent. If the output you see is 1, then your email was successfully sent.

Check your inbox. You should have received the email:

Congrats, you just sent your first email with Django!

Thank you for reading all the way through, and if you enjoyed it, please leave a comment below.

How to Build a Payment Gateway with Django and PayPal: A Step-by-Step Guide

kihuni — Wed, 11 Jun 2025 03:12:03 +0000

Hey there, today we’re diving into an exciting project: building a Payment Gateway API using Django and PayPal! A Payment Gateway API is a RESTful service that lets businesses accept online payments securely, and we’ll create one you can deploy and use. By the end, you’ll have a working system (like Payment-gateway) to handle transactions with ease. Let’s get started!

Why Build a Payment Gateway?

A payment gateway is like a digital cashier for online stores, securely processing payments. Integrating PayPal with Django gives you a reliable, user-friendly solution without starting from scratch. This project uses minimal data (name, email, amount), skips authentication for simplicity, and includes automated tests.

What You’ll Need

Before we jump in, ensure you have:

Python 3.12: Check with python --version.
Django 5.0.6 and Django REST Framework 3.15.1: For the API backbone.
A PayPal Developer Account: To get API credentials (see below).
PostgreSQL 16 or above: For database management.
Git: For version control.
Basic knowledge of Python, Django, and REST APIs.

How to Get PayPal Credentials

To integrate PayPal, you need a Client ID and Secret.

Here’s how to get them:

Sign Up or Log In:

Go to the PayPal Developer Portal and log in with your PayPal account.

Create an App:

Click Log in to Dashboard > My Apps & Credentials.
Under REST API apps, click Create App

Give it a name (e.g., DjangoPaymentGateway) and select your sandbox account.

Get Credentials:

After creating the app, you’ll see a Client ID and a Secret under the app details.

Copy these values, they’ll go into your .env file later.

Sandbox Mode:

For testing, we will use the sandbox environment. Switch to live mode in production after testing.

Save Securely:

Store them in a safe place (not hardcoded in your code!).

Step-by-Step Guide

Step 1. Project Setup

Start by setting up a new Django project.

Create a folder and cd into it

mkdir payment_gateway
cd payment_gateway

Create a virtual environment and activate it

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

Install dependencies:

pip install django==5.0.6 djangorestframework==3.15.1 paypalrestsdk==1.13.1 psycopg2-binary==2.9.9 gunicorn==22.0.0 whitenoise==6.7.0 python-dotenv==1.0.1

Create a django project and an app

django-admin startproject payment_gateway .
python manage.py startapp payments

Configure Settings

Configure the Django project’s environment, database, middleware, PostgreSQL, and PayPal

from pathlib import Path
import os
from dotenv import load_dotenv
import paypalrestsdk


load_dotenv()


# Build paths inside the project like this: BASE_DIR / 'subdir'.
BASE_DIR = Path(__file__).resolve().parent.parent


# Quick-start development settings - unsuitable for production

# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY = os.getenv('SECRET_KEY')

# SECURITY WARNING: don't run with debug turned on in production!
#DEBUG = True # development
DEBUG = False

ALLOWED_HOSTS = [
    'payment-gateway-api-2c52.onrender.com',
    'localhost',  # For local testing
    '127.0.0.1',  # For local testing
]

PAYPAL_CLIENT_ID = os.getenv('PAYPAL_CLIENT_ID', '')
PAYPAL_CLIENT_SECRET = os.getenv('PAYPAL_CLIENT_SECRET', '')
PAYPAL_MODE = os.getenv('PAYPAL_MODE', 'sandbox')


paypalrestsdk.configure({
  "mode": PAYPAL_MODE,
  "client_id": PAYPAL_CLIENT_ID,
  "client_secret": PAYPAL_CLIENT_SECRET
})

# Application definition

INSTALLED_APPS = [

  "payments",
  "rest_framework",

]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.AllowAny',
    ]
}

MIDDLEWARE = [

    'whitenoise.middleware.WhiteNoiseMiddleware',

]

ROOT_URLCONF = 'payment_gateway.urls'

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

WSGI_APPLICATION = 'payment_gateway.wsgi.application'


# Database
# https://docs.djangoproject.com/en/5.2/ref/settings/#databases

# DATABASES = {
#     'default': {
#         'ENGINE': 'django.db.backends.sqlite3',
#         'NAME': BASE_DIR / 'db.sqlite3',
#     }
# }

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.getenv('DB_NAME', 'payment_gateway'),
        'USER': os.getenv('DB_USER', 'payment_gateway'),
        'PASSWORD': os.getenv('DB_PASSWORD'),
        'HOST': os.getenv('DB_HOST', 'localhost'),
        'PORT': os.getenv('DB_PORT', '5432'),
    }
}

# Static files (CSS, JavaScript, Images)
# https://docs.djangoproject.com/en/5.2/howto/static-files/

STATIC_URL = 'static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'
# Default primary key field type
# https://docs.djangoproject.com/en/5.2/ref/settings/#default-auto-field

DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'

Create a .env file:

DB_NAME=payment_gateway
DB_USER=payment_gateway
DB_PASSWORD=payment_gateway
DB_HOST=localhost
DB_PORT=5432
SECRET_KEY=your_secret_key
PAYPAL_CLIENT_ID=your_paypal_client_id
PAYPAL_CLIENT_SECRET=your_paypal_client_secret
PAYPAL_MODE=sandbox
DEBUG=True

Set Up PostgreSQL

Install PostgreSQL and create a Database:

bash

sudo apt update && sudo apt install postgresql postgresql-contrib  # Ubuntu
psql -U postgres

sql

CREATE DATABASE mydb;
CREATE USER myuser WITH PASSWORD 'mypassword';
GRANT ALL PRIVILEGES ON DATABASE mydb TO myuser;

# exit SQL shell
\q

Run migrations:

python manage.py makemigrations
python manage.py migrate

Step 2. Define the Data Model

In payments/models.py, create a Payment model to store transaction details:

from django.db import models

class Payment(models.Model):
    PAYMENT_STATUS = [
        ('created', 'Created'),
        ('approved', 'Approved'),
        ('failed', 'Failed'),
        ('completed', 'Completed'),
    ]

    customer_name = models.CharField(max_length=100)
    customer_email = models.EmailField()
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    paypal_payment_id = models.CharField(max_length=100, unique=True)
    status = models.CharField(max_length=20, choices=PAYMENT_STATUS, default='completed')
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return f"{self.customer_name} - {self.amount}"

This tracks payment details and statuses.

Step 3. Build the API

Let’s create the endpoints to initiate, execute, cancel, and check payments.

Serializers
In payments/serializers.py, define a serializer:

payments/serializers.py

from rest_framework import serializers
from .models import Payment

class PaymentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Payment
        fields = '__all__'
        read_only_fields = ['status', 'paypal_payment_id', 'created_at']

Views
In payments/views.py, implement the API logic:

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from .models import Payment
from .serializers import PaymentSerializer
import paypalrestsdk
import logging

logger = logging.getLogger(__name__)

class PaymentCreateView(APIView):
    def post(self, request):
        try:
            serializer = PaymentSerializer(data=request.data)
            if not serializer.is_valid():
                return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

            data = serializer.validated_data

            payment = paypalrestsdk.Payment({
                "intent": "sale",
                "payer": {"payment_method": "paypal"},
                "redirect_urls": {
                    "return_url": "https://payment-gateway-api-2c52.onrender.com/api/v1/payment/execute",
                    "cancel_url": "https://payment-gateway-api-2c52.onrender.com/api/v1/payment/cancel"
                },
                "transactions": [{
                    "item_list": {
                        "items": [{
                            "name": "Business Payment",
                            "sku": "001",
                            "price": str(data['amount']),
                            "currency": "USD",
                            "quantity": 1
                        }]
                    },
                    "amount": {
                        "total": str(data['amount']),
                        "currency": "USD"
                    },
                    "description": f"Payment by {data['customer_name']}"
                }]
            })

            if payment.create():
                new_payment = Payment.objects.create(
                    customer_name=data['customer_name'],
                    customer_email=data['customer_email'],
                    amount=data['amount'],
                    paypal_payment_id=payment.id,
                    status='created'
                )
                return Response({
                    "status": "success",
                    "payment_id": new_payment.id,
                    "paypal_payment_id": payment.id,
                    "approval_url": next(link.href for link in payment.links if link.rel == "approval_url")
                }, status=status.HTTP_201_CREATED)

            logger.error(f"PayPal payment creation failed: {payment.error}")
            return Response({"status": "error", "message": str(payment.error)}, status=status.HTTP_400_BAD_REQUEST)
        except Exception as e:
            logger.error(f"Error in PaymentCreateView: {str(e)}", exc_info=True)
            return Response({
                "status": "error",
                "message": f"An unexpected error occurred: {str(e)}"
            }, status=status.HTTP_500_INTERNAL_SERVER_ERROR)

class PaymentStatusView(APIView):
    def get(self, request, pk):
        try:
            payment = Payment.objects.get(id=pk)
            serializer = PaymentSerializer(payment)
            return Response({
                "payment": serializer.data,
                "status": "success",
                "message": "Payment details retrieved successfully."
            }, status=status.HTTP_200_OK)
        except Payment.DoesNotExist:
            return Response({
                "status": "error",
                "message": "Payment not found."
            }, status=status.HTTP_404_NOT_FOUND)
        except Exception as e:
            logger.error(f"Error in PaymentStatusView for pk={pk}: {str(e)}", exc_info=True)
            return Response({
                "status": "error",
                "message": "An unexpected error occurred."
            }, status=status.HTTP_500_INTERNAL_SERVER_ERROR)

class PaymentExecuteView(APIView):
    def get(self, request):
        try:
            payment_id = request.GET.get('paymentId')
            payer_id = request.GET.get('PayerID')
            if not payment_id or not payer_id:
                return Response({
                    "status": "error",
                    "message": "Missing paymentId or PayerID. Please ensure the payment is approved via PayPal."
                }, status=status.HTTP_400_BAD_REQUEST)

            payment = paypalrestsdk.Payment.find(payment_id)
            if payment.execute({"payer_id": payer_id}):
                db_payment = Payment.objects.get(paypal_payment_id=payment_id)
                db_payment.status = 'completed'
                db_payment.save()
                return Response({
                    "status": "success",
                    "message": "Payment executed successfully",
                    "payment_id": db_payment.id
                }, status=status.HTTP_200_OK)
            else:
                error = payment.error
                logger.error(f"Payment execution failed: {error}")
                if error.get('name') == 'PAYMENT_NOT_APPROVED_FOR_EXECUTION':
                    return Response({
                        "status": "error",
                        "message": "Payment not approved by payer. Please complete approval on PayPal."
                    }, status=status.HTTP_400_BAD_REQUEST)
                return Response({
                    "status": "error",
                    "message": str(error)
                }, status=status.HTTP_400_BAD_REQUEST)
        except paypalrestsdk.ResourceNotFound:
            return Response({
                "status": "error",
                "message": "Payment not found"
            }, status=status.HTTP_404_NOT_FOUND)
        except Payment.DoesNotExist:
            return Response({
                "status": "error",
                "message": "Payment not found"
            }, status=status.HTTP_404_NOT_FOUND)
        except Exception as e:
            logger.error(f"Error in PaymentExecuteView: {str(e)}", exc_info=True)
            return Response({
                "status": "error",
                "message": f"An unexpected error occurred: {str(e)}"
            }, status=status.HTTP_500_INTERNAL_SERVER_ERROR)

class PaymentCancelView(APIView):
    def get(self, request):
        try:
            payment_id = request.GET.get('paymentId')
            if not payment_id:
                return Response({
                    "status": "error",
                    "message": "Missing paymentId"
                }, status=status.HTTP_400_BAD_REQUEST)

            db_payment = Payment.objects.get(paypal_payment_id=payment_id)
            db_payment.status = 'cancelled'
            db_payment.save()
            return Response({
                "status": "success",
                "message": "Payment cancelled successfully",
                "payment_id": db_payment.id
            }, status=status.HTTP_200_OK)
        except Payment.DoesNotExist:
            return Response({
                "status": "error",
                "message": "Payment not found"
            }, status=status.HTTP_404_NOT_FOUND)
        except Exception as e:
            logger.error(f"Error in PaymentCancelView: {str(e)}", exc_info=True)
            return Response({
                "status": "error",
                "message": f"An unexpected error occurred: {str(e)}"
            }, status=status.HTTP_500_INTERNAL_SERVER_ERROR)

URLs
In payments/urls.py:

payments/urls.py

from django.urls import path
from .views import PaymentCreateView, PaymentStatusView, PaymentExecuteView, PaymentCancelView

urlpatterns = [
    path('payments/', PaymentCreateView.as_view(), name='initiate-payment'),
    path('payments/<int:pk>/', PaymentStatusView.as_view(), name='payment-status'),
    path('payment/execute/', PaymentExecuteView.as_view(), name='payment-execute'),
    path('payment/cancel/', PaymentCancelView.as_view(), name='payment-cancel'),
]

In payment_gateway/urls.py:

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

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/v1/', include('payments.urls')),
]

Step 4. Test Your API

Create tests in payments/tests.py to ensure everything works:

from django.urls import reverse
from rest_framework import status
from rest_framework.test import APITestCase
from unittest.mock import patch, MagicMock
import paypalrestsdk

class PaymentTests(APITestCase):
    def setUp(self):
        # Mock PayPal payment
        self.mock_payment = MagicMock()
        self.mock_payment.id = "PAY-123456"
        self.mock_payment.create = lambda: True
        # Mock links as a list of MagicMock objects with rel and href attributes
        link = MagicMock()
        link.rel = "approval_url"
        link.href = "https://paypal.com/approve"
        self.mock_payment.links = [link]
        self.mock_payment.execute = lambda data: True

    @patch('paypalrestsdk.Payment')
    def test_get_payment_status_success(self, MockPayment):
        MockPayment.return_value = self.mock_payment
        create_url = reverse('initiate-payment')
        data = {
            "customer_name": "John Smith",
            "customer_email": "john@example.com",
            "amount": 30.00
        }
        create_response = self.client.post(create_url, data, format='json')
        payment_id = create_response.data.get("payment_id")
        self.assertEqual(create_response.status_code, status.HTTP_201_CREATED)

        status_url = reverse('payment-status', args=[payment_id])
        response = self.client.get(status_url)
        self.assertEqual(response.status_code, status.HTTP_200_OK)
        self.assertEqual(response.data["payment"]["customer_name"], "John Smith")

    def test_create_payment_missing_fields(self):
        url = reverse('initiate-payment')
        data = {
            "customer_email": "incomplete@example.com"
        }
        response = self.client.post(url, data, format='json')
        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)

    def test_create_payment_invalid_amount(self):
        url = reverse('initiate-payment')
        data = {
            "customer_name": "Test User",
            "customer_email": "test@example.com",
            "amount": "invalid"
        }
        response = self.client.post(url, data, format='json')
        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)

    @patch('paypalrestsdk.Payment')
    def test_payment_execute_success(self, MockPayment):
        MockPayment.return_value = self.mock_payment
        MockPayment.find.return_value = self.mock_payment
        create_url = reverse('initiate-payment')
        data = {
            "customer_name": "John Smith",
            "customer_email": "john@example.com",
            "amount": 30.00
        }
        create_response = self.client.post(create_url, data, format='json')
        payment_id = create_response.data.get("payment_id")
        self.assertEqual(create_response.status_code, status.HTTP_201_CREATED)

        execute_url = reverse('payment-execute') + f'?paymentId=PAY-123456&PayerID=123'
        response = self.client.get(execute_url)
        self.assertEqual(response.status_code, status.HTTP_200_OK)
        self.assertEqual(response.data["status"], "success")

    @patch('paypalrestsdk.Payment')
    def test_payment_execute_not_found(self, MockPayment):
        # Mock ResourceNotFound with a mock response object
        mock_response = MagicMock()
        mock_response.status_code = 404
        MockPayment.find.side_effect = paypalrestsdk.ResourceNotFound(response=mock_response)
        execute_url = reverse('payment-execute') + f'?paymentId=INVALID&PayerID=123'
        response = self.client.get(execute_url)
        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
        self.assertEqual(response.data["status"], "error")

    @patch('paypalrestsdk.Payment')
    def test_payment_cancel_success(self, MockPayment):
        MockPayment.return_value = self.mock_payment
        create_url = reverse('initiate-payment')
        data = {
            "customer_name": "John Smith",
            "customer_email": "john@example.com",
            "amount": 30.00
        }
        create_response = self.client.post(create_url, data, format='json')
        payment_id = create_response.data.get("payment_id")
        self.assertEqual(create_response.status_code, status.HTTP_201_CREATED)

        cancel_url = reverse('payment-cancel') + f'?paymentId=PAY-123456'
        response = self.client.get(cancel_url)
        self.assertEqual(response.status_code, status.HTTP_200_OK)
        self.assertEqual(response.data["status"], "success")

    def test_payment_cancel_not_found(self):
        cancel_url = reverse('payment-cancel') + f'?paymentId=INVALID'
        response = self.client.get(cancel_url)
        self.assertEqual(response.status_code, status.HTTP_404_NOT_FOUND)
        self.assertEqual(response.data["status"], "error") 
    @patch('paypalrestsdk.Payment')
    def test_payment_execute_missing_payer_id(self, MockPayment):
        mock_payment = MagicMock()
        mock_payment.id = "PAY-123456"
        MockPayment.find.return_value = mock_payment
        execute_url = reverse('payment-execute') + '?paymentId=PAY-123456'
        response = self.client.get(execute_url)
        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
        self.assertEqual(response.data["message"], "Missing paymentId or PayerID. Please ensure the payment is approved via PayPal.")

Run tests:

python manage.py test

Step 5. Deploy with CI/CD

Set up GitHub Actions in .github/workflows/django.yml:

name: Django CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:17.2
        env:
          POSTGRES_DB: ${{ secrets. DB_NAME}}
          POSTGRES_USER: ${{ secrets.DB_USER }}
          POSTGRES_PASSWORD:  ${{ secrets.DB_PASSWORD }}
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    env:
      SECRET_KEY: ${{ secrets.SECRET_KEY }}
      PAYPAL_CLIENT_ID: ${{ secrets.PAYPAL_CLIENT_ID }}
      PAYPAL_CLIENT_SECRET: ${{ secrets.PAYPAL_CLIENT_SECRET }}
      DB_NAME: ${{ secrets. DB_NAME}}
      DB_USER: ${{ secrets.DB_USER }}
      DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
      DB_HOST: ${{ secrets.DB_HOST }}
      DB_PORT: 5432

    steps:
    - uses: actions/checkout@v2

    - name: Set up Python '3.10'
      uses: actions/setup-python@v2
      with:
        python-version: '3.10'

    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt

    - name: Wait for PostgreSQL
      run: |
        until pg_isready -h localhost -p 5432; do sleep 1; done

    - name: Run migrations
      run: |
        python manage.py migrate

    - name: Collect static files
      run: |
        python manage.py collectstatic --noinput

    - name: Run tests
      run: |
        python manage.py test

    - name: Deploy to Render
      if: github.ref == 'refs/heads/main' && success()
      run: |
        curl -X POST ${{ secrets.RENDER_DEPLOY_HOOK }}

Deploy to Render:

Push to GitHub.
Connect to Render, set environment variables (matching .env), and use:
Build Command: pip install -r requirements.txt && python manage.py migrate
Start Command: gunicorn payment_gateway.wsgi:application

6. Common Pitfalls & Fixes

PayPal Error (PAYMENT_NOT_APPROVED_FOR_EXECUTION): I hit this when testing manually without approving the payment. Ensure the user follows the approval_URL and includes the Payer_ID.
Test Failures: Fixed by mocking PayPal responses correctly. Check tests.py for details.
Database Issues: Use PostgreSQL to avoid local vs. production mismatches.

7. Test It Out!

Try it live:

{
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "amount": 50.00
}

Follow the approval_url, approve or cancel, and check the status with:

https://payment-gateway-api-2c52.onrender.com/api/v1/payments/1

Conclusion

You’ve now built a Payment Gateway API with Django and PayPal!. Experiment by adding a frontend or more features,
like refunds. Happy coding!

GitHub repo:
Payment-Gateway
Questions? Drop a comment below!

`Lets-Collab`: Building a Secure Collaboration Platform with Django, React, and Permit.io

kihuni — Sun, 04 May 2025 07:38:41 +0000

This is a submission for the Permit.io Authorization Challenge: API-First Authorization Reimagined

What I Built

Lets-Collab is a full-stack web application that enables users to collaborate on projects and tasks while enforcing strict access control policies. The app supports two main user roles:

Admins (e.g., admin users) can access all resources, including creating projects, managing tasks, and viewing audit logs to track user actions.
Members (e.g., newuser): Can list projects, create tasks within those projects, but are restricted from accessing audit logs.

Here’s a breakdown of the key features:

Project and Task Management:

Users can create and list projects and tasks via a clean React frontend.
The backend, built with Django and Django REST Framework, exposes APIs (/api/projects/, /api/tasks/, /api/audit_logs/) for managing these resources.

Authorization with Permit.io:

Integrated Permit.io for externalized authorization.

Configured policies in Permit.io to enforce declarative rules:

Admins have full access to all resources (*) for all actions (read, create, update, delete).
Members can list projects (read on projects), create tasks (create on tasks), but are explicitly denied access to audit logs (audit_logs).
Used Permit.check() to dynamically evaluate permissions for each API request, logging allowed actions to an AuditLog model.

Audit Logging:

Implemented audit logs to track user actions (e.g., project_read, task_create) for transparency and accountability.
Only admins can view audit logs, ensuring sensitive data is protected.

Frontend with React:

Built a responsive UI with React, featuring a Dashboard for managing projects and tasks, and an Access Control Dashboard for admins to view audit logs.
Added error handling to gracefully manage permission denials (e.g., “Audit logs are restricted to admins only” for non-admins).

Demo

Here’s a quick demo of CollabSphere in action:
Member Experience (newuser):

Navigate to the Dashboard (/):

List projects: Successfully displays all projects.

Create a task: Successfully adds a task to a selected project.

Attempt to create a project: Denied (403 Forbidden), as members cannot create projects.

Navigate to the Access Control Dashboard (/access-control):

Denied access to audit logs with a message: “Audit logs are restricted to admins only.”

Admin Experience (admin):
Log in as admin (username: admin, password: 2025DEVChallenge).

Navigate to the Dashboard (/):
List projects and tasks: Successfully displays all data.

Create a project and task: Successfully adds new resources.

Navigate to the Access Control Dashboard (/access-control):
View audit logs: Successfully displays logs of all user actions (e.g., “User admin performed project_read on projects at [timestamp]”).

You can try the live demo here:

Deployed URL: https://letscollab-eight.vercel.app/

Test Credentials:

Admin: admin / 2025DEVChallenge
Member: newuser / 2025DEVChallenge

Project Repo

The source code for Let's-Collab is available on GitHub, split into two repositories:

Backend: https://github.com/kihuni/Lets-Collab-API

Contains the Django backend, including the PermitPermission class, API endpoints, and audit logging logic.

Frontend: https://github.com/kihuni/Lets-Collab-frontend

Contains the React frontend with the Dashboard and Access Control Dashboard components.

My Journey

Building Lets-Collab for the Permit.io Authorization Challenge was a rollercoaster of learning and problem-solving. Here’s a glimpse into my journey:

Starting Point: I began with a basic Django-React app for managing projects and tasks, using a mocked authorization system. The challenge required integrating Permit.io for API-first authorization, which was new to me.
Learning Permit.io: I dove into Permit.io’s documentation to understand its Policy Decision Point (PDP) and how to define roles, resources, and policies. Setting up the initial policies (e.g., admin with full access, member with restricted access) was straightforward, but integrating them into Django posed challenges.
Challenge 1: Async Issues: The Permit.io SDK’s Permit.check() method is asynchronous, but Django is synchronous by default. I encountered a RuntimeWarning: coroutine 'Permit.check' was never awaited error. I fixed this by using asyncio.run() for development, learning that async_to_sync would be better for production with an async server like Uvicorn.
Challenge 2: Policy Misconfiguration: Initially, Permit.check() returned False for all requests, denying access to both admin and newuser. This was due to a mismatch between resource names (projects in the code vs. project in Permit.io) and an incorrect API key. I debugged this by adding detailed logging, aligning resource names, and verifying the API key in Permit.io’s dashboard.
Challenge 3: Frontend Linting: My React frontend had ESLint no-unused-vars warnings for unused err variables in catch blocks. I fixed this by using err.message to provide specific error messages, improving user experience and code quality.
Final Touches: I added input validation in the frontend, visual indicators for expired tasks, and ensured the app was deployable on Render and Vercel. Testing with both admin and newuser confirmed that access control worked as expected.

This journey taught me the importance of externalized authorization, the nuances of integrating async libraries with synchronous frameworks, and the value of clean code practices. Despite the challenges, seeing CollabSphere come together with secure, scalable authorization was incredibly rewarding.

API-First Authorization

The Permit.io Authorization Challenge emphasized API-first authorization, a paradigm where authorization logic is decoupled from the application and managed externally via APIs. Lets-Collab embraces this approach by leveraging Permit.io to enforce access control, aligning with the challenge’s goal of reimagining authorization in an API-first world.

Here’s how Lets-Collab implements API-first authorization:

Externalized Authorization with Permit.io: Instead of hardcoding access control logic in the Django backend, I offloaded it to Permit.io. The PermitPermission class calls Permit.check() for each API request, querying Permit.io’s PDP (https://cloudpdp.api.permit.io) to determine if the action is allowed.

Declarative Policies: I defined policies in Permit.io’s dashboard using a declarative model:

Roles: admin, member.
Resources: projects, tasks, audit_logs.
Actions: read, create, update, delete.

Policies: admin gets full access (*), while member is restricted to read on projects and create on tasks, with an explicit deny on audit_logs.

Scalability and Flexibility: By using Permit.io, I can update access control policies without changing the application code. For example, adding a new role (e.g., guest) or modifying permissions can be done via Permit.io’s dashboard, making the system scalable and adaptable.
Auditability: The app logs allowed actions to the AuditLog model, providing a clear audit trail of user activities, which is crucial for security and compliance in an API-first architecture.

API-first authorization with Permit.io allowed me to focus on building Lets-Collab core features while ensuring robust, maintainable access control. It also highlighted the power of decoupling authorization logic, enabling faster iteration and better security practices.

Conclusion

Lets-Collab demonstrates how API-first authorization can enhance a collaborative platform, ensuring secure and role-based access control with Permit.io. I’m proud of the result and grateful for the learning experience this challenge provided. I hope you enjoy exploring Let's-Collab as much as I enjoyed building it!

Build Your First Blog with Django: Part 1 - Setting Up Your Development Environment

kihuni — Thu, 01 May 2025 06:19:12 +0000

Ever dreamed of creating your website but felt overwhelmed by the techy details? Say hello to Django, the Python-powered web framework that makes building web apps, like a fully functional blog, surprisingly simple!

In this mini-series, we’ll guide you step by step to craft a blog app from scratch, even if you’re new to web development. You’ll learn how to set up Django, create blog posts, and display them on a sleek webpage, all while mastering concepts like models, views, and templates.

By the end, you’ll have a working blog and the skills to build your web projects. Ready to dive into the world of Django and create something awesome? Let’s code!

In Part 1, we’ll focus on setting up your development environment and testing it to ensure everything works. This foundation is crucial for building our blog app in the next posts. Let’s make sure you’re ready to roll!

Prerequisites
What is Django?
Why Use Django for a Blog App?
Setting Up the Development Environment
- Step 1: Install Python
- Step 2: Create a Virtual Environment
- Step 3: Install Django
- Step 4: Create a Django Project
- Step 5: Run the Development Server
What’s Next?

Prerequisites

This series is designed for beginners, so we’ll keep things simple. To follow along, you’ll need:

A computer with Windows, macOS, or Linux.
Python 3.8 or higher installed (we’ll guide you through checking and installing it).
A text editor like VS Code, PyCharm, or even Notepad (VS Code is recommended for its Python support).
Basic command-line knowledge (e.g., how to open a terminal and run commands). Don’t worry if you’re new—we’ll explain each step!
An internet connection to download Python and Django.

No prior Django or web development experience is required. If you know some Python (like variables or functions), that’s a bonus, but we’ll explain everything as we go.

What is Django?

Django is a high-level web framework written in Python that makes building web applications fast, secure, and scalable. Think of it as a toolbox packed with pre-built components, user authentication, database management, and templates that save you time and effort. Whether you’re creating a blog, an e-commerce site, or a social platform, Django streamlines development with a clear structure and robust tools.

Django follows the Model-View-Template (MVT) pattern, organizing your code into:

Models: Define your data (e.g., blog posts).
Views: Handle the logic (e.g., fetching posts).
Templates: Create the visuals (e.g., HTML pages).

It includes an Object-Relational Mapper (ORM) to interact with databases using Python code, a built-in admin panel for managing content, and strong security features to protect your app. For our blog app, Django will help us quickly set up a system to create, display, and manage posts. It’s beginner-friendly, powers major sites like Instagram and Pinterest, and has a vibrant community with excellent documentation.

Why Use Django for a Blog App?

A blog app needs common features: posts, comments, user accounts, and an admin interface. Django is perfect because it provides these components out of the box, letting you focus on customizing your app rather than building from scratch. For example:

Django’s ORM simplifies database tasks, like storing blog posts.
Its admin panel lets you manage posts without extra coding.
Built-in security protects against threats like SQL injection.

Django’s rapid development approach means you can prototype your blog quickly. Its scalability ensures it can grow with your audience, and the Python syntax is approachable for beginners. In this mini-series, we’ll use Django to build a blog app while learning key web development concepts. Part 1 sets the stage by getting your environment ready.

Setting Up the Development Environment

Let’s prepare your computer to run Django. This involves installing Python, creating a virtual environment, installing Django, setting up a project, and running a test server. We’ll break it down into clear steps.

Step 1: Install Python

Django requires Python 3.8 or higher. To check if Python is installed:

Open a terminal:

Windows: Press Win + R, type cmd, and press Enter.
macOS: Search for “Terminal” in Spotlight.
Linux: Open your terminal app.

Run:

python --version

or

python3 --version

If you see a version like Python 3.8.0 or higher, you’re good. If not, download Python from python.org:

Choose the latest version (e.g., 3.11).
Follow the installer, ensuring you check “Add Python to PATH” on Windows.
Verify installation by running python --version again.

Step 2: Create a Virtual Environment

A virtual environment is like a sandbox for your project’s dependencies, keeping them separate from other projects. This prevents conflicts (e.g., different projects needing different Django versions).

Create a folder for your project:

mkdir my_blog
cd my_blog

Create a virtual environment named venv:

python -m venv venv

Activate it:

Windows:

venv\Scripts\activate

macOS/Linux:


source venv/bin/activate

Your terminal prompt should change (e.g., (venv) appears), indicating the virtual environment is active.

Step 3: Install Django

With the virtual environment active, install Django using pip (Python’s package manager):

pip install django

Verify the installation:

django-admin --version

You should see a version like 4.2.7 (or newer). If not, ensure the virtual environment is active and try again.

Step 4: Create a Django Project

A Django project is the container for your web app, holding settings and apps. Create one named blog_project:

django-admin startproject blog_project
cd blog_project

blog_project/
├── manage.py
└── blog_project/
    ├── __init__.py
    ├── settings.py
    ├── urls.py
    ├── asgi.py
    └── wsgi.py

manage.py: A script for running Django commands.
settings.py: Configures your project (e.g., apps, database).
urls.py: Maps URLs to your app’s pages.

Step 5: Run the Development Server

Django includes a lightweight server for testing. Start it:

python manage.py runserver

Open your browser and visit http://127.0.0.1:8000. You should see Django’s welcome page, a green rocket with “The install worked successfully! Congratulations!” This confirms your setup is working.

If you see an error (e.g., “port in use”), stop the server with Ctrl + C and try:

python manage.py runserver 8001

Then visit http://127.0.0.1:8001. Check Django’s documentation for troubleshooting.

What’s Next?

You’ve set up Django and confirmed it works—great job! In Part 2, we’ll create the blog app, define a Post model to store blog posts, and apply database migrations. Future posts will cover displaying posts, setting up the admin panel, and more.

For now, explore your project folder or try re-running the server. Share your progress or questions in the comments below, and check Django’s documentation for extra help. Stay tuned for the next part of our mini-series!

Building a Secure JWT Authentication System with Django

kihuni — Wed, 30 Apr 2025 06:42:33 +0000

I recently implemented a custom authentication system for my Django project, Shopease-API, using JSON Web Tokens (JWT).

The system includes:

Email verification at signup to ensure that email addresses are unique and valid.
Secure login with access and refresh tokens for seamless user sessions.
Token-based authentication using rest_framework_simplejwt for robust security.

In this post, I’ll walk you through the step-by-step process of building this system, from setting up the custom user model to creating the authentication endpoints. Whether you’re a developer diving into the Django REST Framework, this journey offers valuable insights and practical tips!

Why Choose JWT for Shopease-API?

Shopease-API is an e-commerce platform I’m building using Django, designed to handle user authentication, product listings, carts, and orders. I opted for JWT for its stateless nature, scalability, and compatibility with modern APIs. My specific needs included:

Email-based authentication: Users sign in with their email and password, eliminating the need for usernames.
Email verification: This enforces unique email addresses and validates user input.
Secure token management: Access tokens are used for short-term authentication, while refresh tokens allow for session renewal.
Logout with token blacklisting: This feature prevents the reuse of tokens.
Auto-login after signup: To ensure a frictionless user experience.

I chose rest_framework_simplejwt for its reliable JWT implementation, which includes token blacklisting. The authentication system is integrated within a modular users' Django app, keeping the codebase clean and maintainable.

The Authentication Flow

Here’s how the Shopease-API authentication system works:

Signup (/api/auth/register/): Users register with an email and password. The system validates the email for uniqueness, hashes the password, and returns access and refresh tokens for auto-login.
Login (/api/auth/login/): Users authenticate with email and password, receiving new access and refresh tokens.
Logout (/api/auth/logout/): Users send their refresh token to blacklist it, requiring an access token in the header for authentication.
Token Refresh (/api/auth/token/refresh/): Users refresh their access token using the refresh token

Step-by-Step Implementation

Let’s break down the code, organized in the user's app.

Step 1: Custom User Model (users/models.py)

I created a CustomUser model using Django’s AbstractBaseUser to support email-based authentication.

from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin, BaseUserManager
from django.db import models
from django.utils import timezone

class CustomUserManager(BaseUserManager):
    def create_user(self, email, password=None, **extra_fields):
        if not email:
            raise ValueError("Email must be provided")
        email = self.normalize_email(email)
        user = self.model(email=email, **extra_fields)
        user.set_password(password)
        user.save(using=self._db)
        return user

    def create_superuser(self, email, password=None, **extra_fields):
        extra_fields.setdefault('is_staff', True)
        extra_fields.setdefault('is_superuser', True)
        return self.create_user(email, password, **extra_fields)

class CustomUser(AbstractBaseUser, PermissionsMixin):
    email = models.EmailField(unique=True)
    is_active = models.BooleanField(default=True)
    is_staff = models.BooleanField(default=False)
    date_joined = models.DateTimeField(default=timezone.now)

    objects = CustomUserManager()
    USERNAME_FIELD = 'email'
    REQUIRED_FIELDS = []

    def __str__(self):
        return self.email

Key Features:

email is the unique identifier (USERNAME_FIELD).
unique=True ensures email uniqueness at the database level.
set_password hashes passwords securely.

Step 2: Serializers (users/serializers.py)

Serializers handle data validation, including email verification.

from rest_framework import serializers
from .models import CustomUser
 “

from rest_framework import serializers
from .models import CustomUser
from rest_framework_simplejwt.serializers import TokenObtainPairSerializer
from django.core.validators import EmailValidator
from django.core.exceptions import ValidationError

class RegisterSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True, min_length=8)

    class Meta:
        model = CustomUser
        fields = ['email', 'password']

    def validate_email(self, value):
        # Validate email format
        validator = EmailValidator()
        try:
            validator(value)
        except ValidationError:
            raise serializers.ValidationError("Invalid email format")
        # Check email uniqueness
        if CustomUser.objects.filter(email=value).exists():
            raise serializers.ValidationError("Email already exists")
        return value

    def create(self, validated_data):
        return CustomUser.objects.create_user(**validated_data)

class CustomTokenObtainPairSerializer(TokenObtainPairSerializer):
    @classmethod
    def get_token(cls, user):
        token = super().get_token(user)
        return token

Key Features:

RegisterSerializer validates email format and uniqueness using EmailValidator and a custom check.
CustomTokenObtainPairSerializer supports email-based login (leveraging USERNAME_FIELD).

Step 3: Views (users/views.py)

Views define the API endpoints.

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status, generics
from rest_framework.permissions import IsAuthenticated
from rest_framework_simplejwt.views import TokenObtainPairView
from rest_framework_simplejwt.tokens import RefreshToken
from rest_framework_simplejwt.exceptions import TokenError
from .models import CustomUser
from .serializers import RegisterSerializer, CustomTokenObtainPairSerializer

class RegisterView(generics.CreateAPIView):
    queryset = CustomUser.objects.all()
    serializer_class = RegisterSerializer

    def create(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = serializer.save()
        refresh = RefreshToken.for_user(user)
        return Response({
            "user": {"email": user.email},
            "refresh": str(refresh),
            "access": str(refresh.access_token),
        }, status=status.HTTP_201_CREATED)

class CustomTokenObtainPairView(TokenObtainPairView):
    serializer_class = CustomTokenObtainPairSerializer

class LogoutView(APIView):
    permission_classes = [IsAuthenticated]

    def post(self, request):
        try:
            refresh_token = request.data.get("refresh")
            if not refresh_token:
                return Response({"error": "Refresh token is required"}, status=status.HTTP_400_BAD_REQUEST)
            token = RefreshToken(refresh_token)
            token.blacklist()
            return Response({"message": "Successfully logged out"}, status=status.HTTP_205_RESET_CONTENT)
        except TokenError as e:
            return Response({"error": f"Invalid refresh token: {str(e)}"}, status=status.HTTP_400_BAD_REQUEST)

Key Features:

RegisterView: Creates users and returns tokens for auto-login.
CustomTokenObtainPairView: Handles secure login with tokens.
LogoutView: Blacklists refresh tokens, requiring an access token for authentication.

Step 4: URLs (shopease/urls.py)

Include app URLs in the project's urls.py.

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

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/auth/', include('users.urls')),
]

Step 5: URLs (users/urls.py)

Define the API endpoints.

from django.urls import path
from .views import RegisterView, CustomTokenObtainPairView, LogoutView
from rest_framework_simplejwt.views import TokenRefreshView

urlpatterns = [
    path('register/', RegisterView.as_view(), name='register'),
    path('login/', CustomTokenObtainPairView.as_view(), name='login'),
    path('token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
    path('logout/', LogoutView.as_view(), name='logout'),
]

Step 6: Settings (shopease/settings.py)

Configure JWT and the custom user model.

from datetime import timedelta

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'rest_framework_simplejwt',
    'rest_framework_simplejwt.token_blacklist',
    'users',
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),
}

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=60),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
    'ROTATE_REFRESH_TOKENS': True,
    'BLACKLIST_AFTER_ROTATION': True,
    'AUTH_HEADER_TYPES': ('Bearer',),
    'AUTH_TOKEN_CLASSES': ('rest_framework_simplejwt.tokens.AccessToken',),
}

AUTH_USER_MODEL = 'users.CustomUser'

Key Features in Action

Email Verification: The RegisterSerializer uses EmailValidator and checks for existing emails, ensuring only valid, unique emails are accepted.
Auto-Login: The RegisterView returns tokens immediately after signup, streamlining the user experience.

Secure Login: The CustomTokenObtainPairView authenticates users and issues access and refresh tokens, with access tokens expiring in 60 minutes for security.
Token-Based Auth: SimpleJWT’s JWTAuthentication validates access tokens for protected endpoints like /logout/.

Logout with Blacklisting: The token_blacklist app ensures refresh tokens are invalidated on logout.

Lessons Learned

Token Distinction: Access tokens authenticate requests, while refresh tokens handle session renewal or blacklisting. Mixing them up causes errors like 401.
Debugging: Logging request headers and payloads is essential for troubleshooting auth issues.
Validation: Combining model-level (unique=True) and serializer-level email checks ensures robust verification.
Testing: Early testing with Postman catches bugs before they impact the system.

That's a wrap! I’m a Django developer with a passion for creating scalable APIs. Let’s connect! GitHub

Understanding Authentication with JWT and Registration with Email Verification: A Case Study with LiveStatusAPI

kihuni — Wed, 09 Apr 2025 07:35:18 +0000

In API development, securing your endpoints and ensuring only legitimate users can access them is paramount. Two key mechanisms for achieving this are JWT (JSON Web Tokens) authentication and email verification during registration. In this article, I’ll break down these concepts, explain how to implement them in a Django project using Django REST Framework (DRF), and demonstrate their application in a real-world project: LiveStatusAPI, a real-time presence tracking API I'm building.

LiveStatusAPI enables applications to monitor user activity, predict response times, and analyze engagement trends. It includes real-time presence tracking, engagement analytics, webhook integration, and role-based access control features.

In this post, I’ll focus on how I rebuilt the user registration and login system for LiveStatusAPI, replacing its basic session-based authentication with JWT and adding email verification to ensure that only verified users can access the API. Let’s dive in!

What is JWT Authentication?

Understanding JWT

JWT (JSON Web Token) is a compact, self-contained standard for securely transmitting information between parties as a JSON object. It’s widely used for authentication in APIs because it’s stateless and scalable. A JWT consists of three parts, separated by dots (.):

Header: Contains metadata about the token, such as the type (JWT) and the signing algorithm (e.g., HMAC SHA256).
Payload: Contains the claims, which are statements about the user (e.g., user ID, email) and additional data (e.g., expiration time).
Signature: Verifies the token’s integrity by combining the encoded header, payload, and a secret key.

For example, a JWT might look like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiMTIzNDU2Nzg5MCIsImV4cCI6MTY3ODkwMTIzNH0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

When decoded, the payload might reveal:

{
  "user_id": "1234567890",
  "exp": 1678901234
}

How JWT Authentication Works

JWT authentication is stateless, meaning the server doesn’t store session information. Here’s the typical flow:
User Logs In: The user sends their credentials (e.g., email and password) to a login endpoint.

Token Generation: The server verifies the credentials and generates a JWT (access token and optionally a refresh token). The access token is short-lived (e.g., 60 minutes), while the refresh token is longer-lived (e.g., 1 day).
Token Usage: The client includes the access token in the Authorization header of subsequent requests (e.g., Authorization: Bearer ).
Token Verification: The server verifies the token’s signature and checks its expiration. If valid, the request is processed; otherwise, it’s rejected.
Token Refresh: When the access token expires, the client can use the refresh token to request a new access token without re-authenticating.

Why Use JWT?

Stateless: No need to store session data on the server, making it ideal for scalable APIs.
Secure: Tokens are signed, ensuring data integrity and authenticity.
Cross-Domain: JWTs can be used across different domains, making them suitable for microservices or single sign-on (SSO).

What is Registration with Email Verification?

The Importance of Email Verification

Email verification is a security measure that ensures a user’s email address is valid and belongs to them before granting access to an application. Without verification, malicious users could register with fake emails, potentially leading to spam accounts or unauthorized access. Email verification typically involves:

User Registration: The user provides their email, username, and password.
Email Sending: The server sends a verification email with a unique link or token to the user’s email address.
Email Verification: The user clicks the link, confirming their email and account is activated.

Why Use Email Verification?

Security: Ensures only legitimate users can access the system.
User Trust: Verifying emails reduces spam and builds trust with users.
Data Quality: Helps maintain a database of valid email addresses for communication.

Implementing JWT Authentication and Email Verification in Django

Let’s walk through the steps to implement JWT authentication and email verification in a Django project using DRF. I’ll use the djangorestframework-simplejwt package for JWT authentication, which provides a robust implementation of JWT with access and refresh tokens.

Step 1: Set Up the Project

Install Dependencies

First, install the necessary packages:
bash

pip install django djangorestframework djangorestframework-simplejwt python-decouple

Add these to your requirements.txt:

django==4.2.7
djangorestframework==3.14.0
djangorestframework-simplejwt==5.3.1
python-decouple==3.8

Configure Django Settings

Update your settings.py to include DRF, rest_framework_simplejwt, and email settings for sending verification emails:

# your_project/settings.py

import os
from datetime import timedelta
from decouple import config

# Define the custom user model (we’ll create this next)
AUTH_USER_MODEL = 'users.CustomUser'

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'rest_framework_simplejwt',
    'users',
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated',
    ),
}

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=60),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
    'ROTATE_REFRESH_TOKENS': True,
    'BLACKLIST_AFTER_ROTATION': True,
    'AUTH_HEADER_TYPES': ('Bearer',),
    'USER_ID_FIELD': 'id',
    'USER_ID_CLAIM': 'user_id',
}

# Email settings for verification
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = config('EMAIL_HOST', default='smtp.gmail.com')
EMAIL_PORT = config('EMAIL_PORT', default=587, cast=int)
EMAIL_USE_TLS = True
EMAIL_HOST_USER = config('EMAIL_HOST_USER')
EMAIL_HOST_PASSWORD = config('EMAIL_HOST_PASSWORD')
DEFAULT_FROM_EMAIL = EMAIL_HOST_USER

Create a .env file to store sensitive information:

# .env
SECRET_KEY=your-django-secret-key
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password

Understanding the Email Settings in Django

Django provides a built-in email-sending framework that can be configured to send emails via various backends (e.g., SMTP, console, file-based). We’re using the SMTP backend (django.core.mail.backends.smtp.EmailBackend) to send emails through an external SMTP server (Gmail, by default). These settings define how Django connects to the SMTP server and sends emails.

Here’s a breakdown of each setting in the configuration:

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend': Specifies the backend Django will use to send emails.
EMAIL_HOST = config('EMAIL_HOST', default='smtp.gmail.com'): Defines the hostname of the SMTP server Django will connect to. The default is smtp.gmail.com.
EMAIL_PORT = config('EMAIL_PORT', default=587, cast=int): Specifies the port number to use when connecting to the SMTP server.
EMAIL_USE_TLS = True: Enables TLS encryption for the connection to the SMTP server.
EMAIL_HOST_USER = config('EMAIL_HOST_USER') - Specifies the email address (username) used to authenticate with the SMTP server.
EMAIL_HOST_PASSWORD = config('EMAIL_HOST_PASSWORD'): Specifies the password to authenticate with the SMTP server.
DEFAULT_FROM_EMAIL = EMAIL_HOST_USER: Sets the default from email address for emails sent by Django.

Setting Up Gmail for Sending Emails

Since the default EMAIL_HOST is smtp.gmail.com, let’s set up Gmail to work with Django. Gmail has strict security measures, so you’ll need to use an App Password instead of your regular Gmail password.

Step 1. Enable 2-Step Verification on Your Gmail Account

Go to your Google Account settings:.
Navigate to Security > 2-Step Verification.
Follow the steps to enable 2-step verification (e.g., using your phone number for verification).

Step 2. Generate an App Password

After enabling 2-step verification, go to Security > App Passwords (or search for “App Passwords” in your Google Account settings).
Click Generate.
Select App as “Mail” and Device as “Other (Custom name)”, then name it (e.g., “Django”).
Click Generate. Google will provide a 16-character App Password (e.g., abcd efgh ijkl mnop).
Copy this password (ignore the spaces).

Step 3. Update Your .env File
Add the Gmail credentials to your .env file using the App Password:

# .env
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password  # e.g., abcdefghijklmnop

Step 4. Test Sending an Email
To confirm the setup works, run a quick test in the Django shell:

python manage.py shell

from django.core.mail import send_mail

send_mail(
    'kamau@gmail.com',
    'This is a test email from Django.',
    'stephenkihuni55@gmail.com',
    ['test-recipient@example.com'],
    fail_silently=False,
)

If the email is sent successfully, your configuration is correct.

If it fails, check the error message:

SMTPAuthenticationError: Likely an issue with EMAIL_HOST_USER or EMAIL_HOST_PASSWORD. Double-check your App Password.
ConnectionRefusedError: Ensure EMAIL_PORT and EMAIL_USE_TLS are correct (587 and True for Gmail).

Set Up URLs

Add the JWT token endpoints to your project’s urls.py:

# your_project/urls.py

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('users.urls')),
    path('api/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),
    path('api/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),
]

Step 2: Create a Custom User Model

Create a CustomUser model to support email verification:

# users/models.py

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

class CustomUser(AbstractUser):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    email = models.EmailField(unique=True)
    verification_token = models.CharField(max_length=36, blank=True, null=True)
    is_verified = models.BooleanField(default=False)

    REQUIRED_FIELDS = ['email']

    def __str__(self):
        return self.username

Run migrations to apply the changes:

python manage.py makemigrations
python manage.py migrate

Step 3: Implement Registration with Email Verification

Create a Registration Serializer

Create a serializer to handle user registration and send a verification email:

# users/serializers.py

from rest_framework import serializers
from django.contrib.auth import get_user_model
from django.core.mail import send_mail
from django.urls import reverse
import uuid

User = get_user_model()

class RegisterSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True, min_length=8)
    email = serializers.EmailField()

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

    def validate_email(self, value):
        if User.objects.filter(email=value).exists():
            raise serializers.ValidationError("A user with this email already exists.")
        return value

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

        verification_token = str(uuid.uuid4())
        user.verification_token = verification_token
        user.save()

        verification_url = self.context['request'].build_absolute_uri(
            reverse('verify-email', kwargs={'token': verification_token})
        )
        subject = 'Verify Your Email Address'
        message = f'Click the link to verify your email: {verification_url}'
        send_mail(
            subject,
            message,
            'from@example.com',
            [user.email],
            fail_silently=False,
        )

        return user

Create Registration and Verification Views
Create views for registration and email verification:

# users/views.py

from rest_framework import generics, status
from rest_framework.response import Response
from rest_framework.permissions import AllowAny
from .serializers import RegisterSerializer
from django.contrib.auth import get_user_model

User = get_user_model()

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

    def create(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = serializer.save()
        return Response({
            "message": "User registered successfully. Please verify your email to activate your account.",
            "user": {
                "id": str(user.id),
                "username": user.username,
                "email": user.email
            }
        }, status=status.HTTP_201_CREATED)

class VerifyEmailView(generics.GenericAPIView):
    permission_classes = [AllowAny]

    def get(self, request, token, *args, **kwargs):
        try:
            user = User.objects.get(verification_token=token)
            if user.is_verified:
                return Response({"message": "Email already verified."}, status=status.HTTP_400_BAD_REQUEST)
            user.is_verified = True
            user.is_active = True
            user.verification_token = None
            user.save()
            return Response({"message": "Email verified successfully. You can now log in."}, status=status.HTTP_200_OK)
        except User.DoesNotExist:
            return Response({"error": "Invalid verification token."}, status=status.HTTP_400_BAD_REQUEST)

Set Up URLs
Add the endpoints to users/urls.py:

# users/urls.py

from django.urls import path
from .views import RegisterView, VerifyEmailView

urlpatterns = [
    path('register/', RegisterView.as_view(), name='register'),
    path('verify-email/<str:token>/', VerifyEmailView.as_view(), name='verify-email'),
]

Step 4: Implement JWT Authentication for Login

Customize the Login Process

Since the CustomUser model uses email as the unique identifier, customize the login process to allow users to log in with their email:

# users/views.py (continued)

from rest_framework_simplejwt.views import TokenObtainPairView
from rest_framework_simplejwt.serializers import TokenObtainPairSerializer
from rest_framework import status
from rest_framework.response import Response

class CustomTokenObtainPairSerializer(TokenObtainPairSerializer):
    def validate(self, attrs):
        email = attrs.get("email")
        password = attrs.get("password")

        if email and password:
            user = User.objects.filter(email=email).first()
            if user and user.check_password(password):
                if not user.is_verified:
                    raise serializers.ValidationError("Please verify your email before logging in.")
                if not user.is_active:
                    raise serializers.ValidationError("User account is inactive.")
                attrs['username'] = user.username
                return super().validate(attrs)
            else:
                raise serializers.ValidationError("Invalid email or password.")
        else:
            raise serializers.ValidationError("Must include 'email' and 'password'.")

class CustomTokenObtainPairView(TokenObtainPairView):
    serializer_class = CustomTokenObtainPairSerializer

    def post(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        return Response({
            "access": serializer.validated_data['access'],
            "refresh": serializer.validated_data['refresh'],
            "user": {
                "id": str(serializer.user.id),
                "username": serializer.user.username,
                "email": serializer.user.email
            }
        }, status=status.HTTP_200_OK)

Update URLs
Add the custom login endpoint:

# users/urls.py

from django.urls import path
from .views import RegisterView, VerifyEmailView, CustomTokenObtainPairView

urlpatterns = [
    path('register/', RegisterView.as_view(), name='register'),
    path('verify-email/<str:token>/', VerifyEmailView.as_view(), name='verify-email'),
    path('login/', CustomTokenObtainPairView.as_view(), name='login'),
]

Case Study: Applying JWT Authentication and Email Verification to LiveStatusAPI

Now that we’ve covered the theory and implementation, let’s see how I applied these concepts to LiveStatusAPI, a real-time presence-tracking API I’ve been building. LiveStatusAPI already had basic user registration and login functionality, but it used session-based authentication and lacked email verification. On Day 1 of my project, I rebuilt these components to use JWT authentication and added email verification to ensure only verified users can access the API.

Step 1: Reviewing the Existing Setup

LiveStatusAPI uses Django and DRF, with a CustomUser modelthat extends AbstractUser and uses a UUID as the primary key. The project had basic registration (POST /api/register/) and login endpoints, but they didn’t enforce email verification, and authentication was session-based.

I started by ensuring the project was running:

cd LiveStatusAPI
source livevenv/bin/activate
git pull # since its open-sourced
pip install -r requirements.txt
python manage.py runserver

Step 2: Configuring JWT and Email Settings

I updated settings.py to replace session-based authentication with JWT and add email settings for verification:

# LiveStatusApi/settings.py

import os
from datetime import timedelta
from decouple import config

AUTH_USER_MODEL = 'users.CustomUser'

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'rest_framework',
    'rest_framework_simplejwt',
    'users',
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticated',
    ),
}

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=60),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
    'ROTATE_REFRESH_TOKENS': True,
    'BLACKLIST_AFTER_ROTATION': True,
    'AUTH_HEADER_TYPES': ('Bearer',),
    'USER_ID_FIELD': 'id',
    'USER_ID_CLAIM': 'user_id',
}

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = config('EMAIL_HOST', default='smtp.gmail.com')
EMAIL_PORT = config('EMAIL_PORT', default=587, cast=int)
EMAIL_USE_TLS = True
EMAIL_HOST_USER = config('EMAIL_HOST_USER')
EMAIL_HOST_PASSWORD = config('EMAIL_HOST_PASSWORD')
DEFAULT_FROM_EMAIL = EMAIL_HOST_USER

I updated the .env file with my Gmail credentials, using an App Password for security:

# .env
SECRET_KEY=your-django-secret-key
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_HOST_USER=your-email@gmail.com
EMAIL_HOST_PASSWORD=your-app-password

Step 3: Updating the CustomUser Model

The existing CustomUser model didn’t have fields for email verification. I added verification_token and is_verified:

# users/models.py

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

class CustomUser(AbstractUser):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    email = models.EmailField(unique=True)
    verification_token = models.CharField(max_length=36, blank=True, null=True)
    is_verified = models.BooleanField(default=False)

    REQUIRED_FIELDS = ['email']

    def __str__(self):
        return self.username

I ran migrations to apply the changes:

python manage.py makemigrations
python manage.py migrate

Step 4: Rebuilding Registration with Email Verification

I created a RegisterSerializer to handle the updated registration process, ensuring users must verify their email before their account is activated:

# users/serializers.py

from rest_framework import serializers
from django.contrib.auth import get_user_model
from django.core.mail import send_mail
from django.urls import reverse
import uuid

User = get_user_model()

class RegisterSerializer(serializers.ModelSerializer):
    password = serializers.CharField(write_only=True, min_length=8)
    email = serializers.EmailField()

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

    def validate_email(self, value):
        if User.objects.filter(email=value).exists():
            raise serializers.ValidationError("A user with this email already exists.")
        return value

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

        verification_token = str(uuid.uuid4())
        user.verification_token = verification_token
        user.save()

        verification_url = self.context['request'].build_absolute_uri(
            reverse('verify-email', kwargs={'token': verification_token})
        )
        subject = 'Verify Your Email Address'
        message = f'Click the link to verify your email: {verification_url}'
        send_mail(
            subject,
            message,
            'from@example.com',
            [user.email],
            fail_silently=False,
        )

        return user

I updated the existing RegisterView and added a VerifyEmailView:

# users/views.py

from rest_framework import generics, status
from rest_framework.response import Response
from rest_framework.permissions import AllowAny
from .serializers import RegisterSerializer
from django.contrib.auth import get_user_model

User = get_user_model()

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

    def create(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = serializer.save()
        return Response({
            "message": "User registered successfully. Please verify your email to activate your account.",
            "user": {
                "id": str(user.id),
                "username": user.username,
                "email": user.email
            }
        }, status=status.HTTP_201_CREATED)

class VerifyEmailView(generics.GenericAPIView):
    permission_classes = [AllowAny]

    def get(self, request, token, *args, **kwargs):
        try:
            user = User.objects.get(verification_token=token)
            if user.is_verified:
                return Response({"message": "Email already verified."}, status=status.HTTP_400_BAD_REQUEST)
            user.is_verified = True
            user.is_active = True
            user.verification_token = None
            user.save()
            return Response({"message": "Email verified successfully. You can now log in."}, status=status.HTTP_200_OK)
        except User.DoesNotExist:
            return Response({"error": "Invalid verification token."}, status=status.HTTP_400_BAD_REQUEST)

I updated users/urls.py to include the email verification endpoint:

# users/urls.py

from django.urls import path
from .views import RegisterView, VerifyEmailView

urlpatterns = [
    path('register/', RegisterView.as_view(), name='register'),
    path('verify-email/<str:token>/', VerifyEmailView.as_view(), name='verify-email'),
]

Step 5: Rebuilding Login with JWT

I replaced the existing session-based login with JWT, customizing the login process to use email:

# users/views.py

from rest_framework_simplejwt.views import TokenObtainPairView
from rest_framework_simplejwt.serializers import TokenObtainPairSerializer
from rest_framework import status
from rest_framework.response import Response

class CustomTokenObtainPairSerializer(TokenObtainPairSerializer):
    def validate(self, attrs):
        email = attrs.get("email")
        password = attrs.get("password")

        if email and password:
            user = User.objects.filter(email=email).first()
            if user and user.check_password(password):
                if not user.is_verified:
                    raise serializers.ValidationError("Please verify your email before logging in.")
                if not user.is_active:
                    raise serializers.ValidationError("User account is inactive.")
                attrs['username'] = user.username
                return super().validate(attrs)
            else:
                raise serializers.ValidationError("Invalid email or password.")
        else:
            raise serializers.ValidationError("Must include 'email' and 'password'.")

class CustomTokenObtainPairView(TokenObtainPairView):
    serializer_class = CustomTokenObtainPairSerializer

    def post(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        return Response({
            "access": serializer.validated_data['access'],
            "refresh": serializer.validated_data['refresh'],
            "user": {
                "id": str(serializer.user.id),
                "username": serializer.user.username,
                "email": serializer.user.email
            }
        }, status=status.HTTP_200_OK)

I updated users/urls.py to include the custom login endpoint:

# users/urls.py

from django.urls import path
from .views import RegisterView, VerifyEmailView, CustomTokenObtainPairView

urlpatterns = [
    path('register/', RegisterView.as_view(), name='register'),
    path('verify-email/<str:token>/', VerifyEmailView.as_view(), name='verify-email'),
    path('login/', CustomTokenObtainPairView.as_view(), name='login'),
]

Step 6: Testing the Implementation

I tested the updated registration and login flow with Postman:

{
    "username": "testuser",
    "email": "testuser@example.com",
    "password": "testpassword123"
}

Response:

{
    "message": "User registered successfully. Please verify your email to activate your account.",
    "user": {
        "id": "some-uuid",
        "username": "testuser",
        "email": "testuser@example.com"
    }
}

I received a verification email with a link like http://localhost:8000/api/verify-email//.

Verify Email (GET /api/verify-email//):
Response:


{
    "message": "Email verified successfully. You can now log in."
}

{
    "email": "testuser@example.com",
    "password": "testpassword123"
}

Response:

{
    "access": "your-access-token",
    "refresh": "your-refresh-token",
    "user": {
        "id": "some-uuid",
        "username": "testuser",
        "email": "testuser@example.com"
    }
}

Conclusion

This implementation sets a secure foundation for LiveStatusAPI. In future articles, I’ll build on this by implementing features like the GET /users/{userId}/presence endpoint to retrieve user presence data, ensuring it’s protected with JWT authentication. I’ll also add caching, webhooks, and analytics, continuing to use LiveStatusAPI as a case study to demonstrate how these concepts apply in a real-world project.

If you have feedback or suggestions for improving LiveStatusAPI, feel free to leave a comment or reach out on GitHub https://github.com/kihuni/LiveStatusAPI.

Secure Image Processing with Pulumi ESC, Clarifai, and pCloud

kihuni — Sat, 05 Apr 2025 17:59:55 +0000

This is a submission for the Pulumi Deploy and Document Challenge: Shhh, It's a Secret!

What I Built

I built a Secure Image Processing Pipeline that processes images to detect labels and securely stores the results in the cloud. The pipeline uses Clarifai for image processing, pCloud for storage, and Pulumi ESC to manage secrets and configurations securely. To make the project more interactive, I added a simple web UI using Flask, allowing users to upload an image, view the detected labels, and access the results file.

Here’s how the pipeline works:

A user uploads an image through the web UI.
The script fetches the Clarifai API key and pCloud credentials from Pulumi ESC.
Clarifai processes the image to detect labels (e.g., dog, pet, animal).
The results are saved locally as a JSON file (e.g., analysis_results_1743817982.json) with a unique timestamp to prevent overwrites.
The UI displays the uploaded image, detected labels, and a result file link.

This project demonstrates secure configuration management using Pulumi ESC to handle sensitive data (API keys and credentials) without hardcoding them in the source code. It also showcases a practical use case for image processing and cloud storage.

Web UI Home Page:

Results Page:

Results File Content

pCloud Storage:

Live Demo Link

Due to connectivity restrictions on PythonAnywhere’s free tier, which blocked outbound HTTPS connections to api.pulumi.com for fetching secrets at runtime, I was unable to deploy the app live within the hackathon timeline. Instead, I’ve tested the app locally and provided detailed screenshots and setup instructions to demonstrate its functionality. You can replicate the app on your local machine by following the setup instructions below.

Setup Instructions
To run the Secure Image Processing Pipeline locally, follow these steps:
Prerequisites

Python 3.8+
Pulumi CLI (for managing ESC environments)
A Clarifai account with an API key
A pCloud account with a username and password
A folder named /hackathon-results in your pCloud account

Steps
Clone the Repository:

git clone https://github.com/kihuni/Secure-Image-Processing-Pipeline.git
cd Secure-Image-Processing-Pipeline

Set Up a Virtual Environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install Dependencies:

pip install -r requirements.txt

The requirements.txt includes:


flask
clarifai-grpc
pcloud
pulumi-esc-sdk

Set Up Pulumi ESC:
Install the Pulumi CLI: Pulumi Installation Guide

Set your Pulumi access token:

export PULUMI_ACCESS_TOKEN="your-access-token"

Create a new ESC environment (or use the existing one):
bash

esc env init kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment

Set the secrets and configurations:

esc env set --secret kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment clarifai:apiKey "your-clarifai-api-key"
esc env set --secret kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment pcloud:username "your-pcloud-email"
esc env set --secret kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment pcloud:password "your-pcloud-password"
esc env set kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment pcloud:folderPath "/hackathon-results"

Run the App Locally:

python app.py

Open http://localhost:5000 in your browser.

Project Repo

The source code for the Secure Image Processing Pipeline is available on GitHub:
Secure-Image-Processing-Pipeline

My Journey

Building the Secure Image Processing Pipeline was a rewarding experience that taught me a lot about secure configuration management, image processing, and web development. Here’s a summary of my journey:

Initial Setup: I started by setting up a Flask app with a simple UI for uploading images. I chose Clarifai for image processing and pCloud for storage due to their free tiers and ease of use.
Integrating Pulumi ESC: I used Pulumi ESC to manage my Clarifai API key and pCloud credentials securely. I initially encountered a 401 Unauthorized error due to an incorrect import of the pulumi_esc_sdk and a malformed environment path. I resolved this by using the correct Client class and fixing the path to kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment.
Challenges with Deployment: I planned to deploy the app on PythonAnywhere, but connectivity restrictions blocked outbound HTTPS connections to api.pulumi.com. I pivoted to a local setup, providing screenshots and detailed setup instructions to demonstrate the app’s functionality.
Adding Unique Filenames: I noticed that multiple requests would overwrite the analysis_results.json file, so I added a timestamp to the filename (e.g., analysis_results_1743817982.json), ensuring each request generates a unique file.
Lessons Learned: This project taught me the importance of secure configuration management and the challenges of deploying on restricted platforms. I also gained experience with Flask, Clarifai, pCloud, and Pulumi ESC, and I’m excited to apply these skills to future projects.

Using Pulumi ESC

Pulumi ESC played a crucial role in ensuring the security of my Secure Image Processing Pipeline. Here’s how I used it:

Environment Setup: I created an ESC environment named kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment to store my secrets and configurations.
Storing Secrets: I stored the Clarifai API key and pCloud credentials as secrets in the ESC environment, ensuring they were encrypted and not exposed in the source code.

esc env set --secret kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment clarifai:apiKey "your-clarifai-api-key"
esc env set --secret kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment pcloud:username "your-pcloud-email"
esc env set --secret kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment pcloud:password "your-pcloud-password"
esc env set kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment pcloud:folderPath "/hackathon-results"

Fetching Secrets: In the app, I used the pulumi-esc-sdk to fetch the secrets at runtime:

from pulumi_esc_sdk import Client
client = Client()
environment = client.open_and_read_environment("kihuni/Secure-Multi-Cloud-Backup-Orchestrator/dev-environment")
clarifai_api_key = environment["clarifai"]["apiKey"]
pcloud_username = environment["pcloud"]["username"]
pcloud_password = environment["pcloud"]["password"]
pcloud_folder_path = environment["pcloud"]["folderPath"]

Security Benefits: Using Pulumi ESC allowed me to keep sensitive data out of my source code and environment variables, reducing the risk of accidental leaks. It also provided a centralized way to manage configurations, making it easy to update secrets without modifying the code.

Conclusion

The Secure Image Processing Pipeline demonstrates how to build a secure, user-friendly application with Pulumi ESC, Clarifai, and pCloud. Although I couldn’t deploy the app live due to platform restrictions, the local setup and detailed documentation showcase its functionality and the benefits of using Pulumi ESC for secure configuration management.

How to Add Google OAuth to Django REST API

kihuni — Tue, 25 Mar 2025 00:42:39 +0000

User authentication is a crucial part of any modern web application, especially APIs that require secure access. Instead of traditional username-password logins, integrating Google OAuth allows users to authenticate seamlessly with their Google accounts. This enhances security, improves user experience, and eliminates the hassle of managing passwords.

In this guide, we’ll walk through how to add Google OAuth authentication to a Django REST API. By the end, users will be able to log in with Google, receive a JSON Web Token (JWT), and access protected API endpoints securely.

We'll cover:

✅ Setting up Google OAuth credentials in the Google Developer Console
✅ Configuring Django REST Framework with JWT authentication
✅ Implementing backend routes to handle Google login

Let’s dive in!

Why Google OAuth for a Django REST API?

For an API focused on project collaboration, Google OAuth with DRF offers:

Seamless Sign-In: Users log in with Google, skipping manual signup.
API Security: JWTs protect endpoints like /projects/ or /contributions/.
Developer Appeal: A trusted, scalable authentication method. This setup enhances user experience, making it quick and reliable for users to access your API.

Setting Up the Project

Let’s create a Django REST API from scratch, using Pipenv for environment management to keep dependencies clean.

Initial Setup
Create a Project Directory:

mkdir ProjectAPI
cd ProjectAPI

Install Dependencies:
Add Django, DRF, and OAuth tools:

pipenv install django djangorestframework django-allauth djangorestframework-simplejwt python-decouple

Activate the Virtual Environment

pipenv shell

Start the Django Project:

pipenv run django-admin startproject ProjectAPI .

Note: The . keeps the project files in the current directory.

Add an App:

pipenv run python manage.py startapp core

Test the Setup:

pipenv run python manage.py runserver

Visit http://localhost:8000/ to confirm it’s working.

Task 1: Set Up Google OAuth Credentials

Google OAuth starts with registering your app in the Developer Console.

Steps:
Step 1. Create a Project:

Visit Google Cloud Console.

Create a project (e.g., "ProjectCollabAPI").
Choose the Organization and Location (if applicable).
Click Create.

Step 2. Enable APIs:

In the Google Cloud Console, select the project you just created.
Navigate to APIs & Services > Library.
Search for "Google+ API" or "People API" .

and click "Enable." This allows your app to access user info.

Step 3. Configure OAuth Consent Screen:

Still on the "APIs & Services", go to the "OAuth consent screen."

You will see a "Google Auth Platform not configured yet" message with a "Get started" button—this is normal for a new project. Click "Get started."

Choose User Type:

Select "External" to allow any Google account to sign in (good for testing). Click "Create."

Add app Information:

App Name: Enter "Project Collaboration API."
User Support Email: Use your Gmail address.
App Logo (optional): Upload a 512x512px image (e.g., a handshake icon).
App Domain (optional): Skip for now unless you have a production domain.
Developer Contact Information: Add your email.
Click "Save and Continue."

Scopes:
Click "Add or Remove Scopes."

Add profile and email (e.g., https://www.googleapis.com/auth/userinfo.profile, https://www.googleapis.com/auth/userinfo.email) to access basic user info.

Click "Update," then "Save and Continue."

Test Users (optional):
If prompted, add your Gmail as a test user for development.

Click "Save and Continue."

Step 4. Create Credentials:

In the left sidebar, go to "APIs & Services" > "Credentials."

Click "Create Credentials" > "OAuth 2.0 Client IDs."

Select "Web application."
Set "Authorized redirect URIs" to:

- http://localhost:8000/auth/google/login/callback/ (for the default Django development server port using localhost).
- http://127.0.0.1:8000/auth/google/login/callback/ (if you access via 127.0.0.1).
- Add additional URIs if you use a different port (e.g., http://localhost:8080/auth/google/login/callback/, http://127.0.0.1:8080/auth/google/login/callback/).

Note: The callback path /auth/google/login/callback/ is the default path used by django-allauth for the Google provider when the base path is /auth/. This path is determined by django-allauth’s URL patterns for the Google provider.

Click "Create" and note your Client ID and Client Secret.

Secure Storage

In .env (create this file in ProjectAPI/):

GOOGLE_CLIENT_ID=your-client-id-here
GOOGLE_CLIENT_SECRET=your-client-secret-here

In ProjectAPI/settings.py:
python

from decouple import config
GOOGLE_CLIENT_ID = config('GOOGLE_CLIENT_ID')
GOOGLE_CLIENT_SECRET = config('GOOGLE_CLIENT_SECRET')

Task 2: Configure JWT for Authenticated Users

For an API app, JWTs provide stateless authentication, ideal for securing endpoints after Google sign-in. Let’s configure the necessary settings in ProjectAPI/settings.py.

Update settings.py

Add the following to enable Django’s authentication, DRF, allauth for Google OAuth, and SimpleJWT for token-based API access:


INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.sites',
    'rest_framework',
    'rest_framework_simplejwt',
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    'allauth.socialaccount.providers.google',
    'core',
]

SITE_ID = 1
AUTHENTICATION_BACKENDS = [
    'django.contrib.auth.backends.ModelBackend',
    'allauth.account.auth_backends.AuthenticationBackend',
]
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ),
}

SOCIALACCOUNT_PROVIDERS = {
    'google': {
        'SCOPE': ['profile', 'email'],
        'AUTH_PARAMS': {'access_type': 'online'},
    }
}

MIDDLEWARE = [
 ...
    'allauth.account.middleware.AccountMiddleware',  # Required for allauth
]
...

Understanding the Settings
Let’s break down what each part does:

INSTALLED_APPS:

'django.contrib.auth': Enables Django’s user authentication system (e.g., User model, login/logout).
'django.contrib.contenttypes': Supports generic relationships, used by other apps.
'django.contrib.sessions': Manages user sessions during the OAuth flow (even though we’ll use JWTs for API access).
'django.contrib.messages': Handles one-time messages (e.g., success notifications).
'django.contrib.staticfiles': Manages static files for the minimal frontend.
'django.contrib.sites': Required by allauth to associate users with a site.
'rest_framework': Adds DRF for API functionality.
'rest_framework_simplejwt': Provides JWT authentication for DRF.
'allauth', 'allauth.account', 'allauth.socialaccount': Core allauth packages for authentication and social logins.
'allauth.socialaccount.providers.google': Enables Google OAuth support.
'core': Your custom app for API logic.

SITE_ID = 1:

Identifies the site your app runs on, required by allauth—the default SITE_ID of 1 matches the first site in the django_site table (created during migration).

AUTHENTICATION_BACKENDS:

'django.contrib.auth.backends.ModelBackend': Default Django backend for username/password authentication.
'allauth.account.auth_backends.AuthenticationBackend': Handles allauth’s authentication, including Google OAuth.

REST_FRAMEWORK:

'DEFAULT_AUTHENTICATION_CLASSES': Sets JWT as the default authentication method for DRF. After Google sign-in, users get a JWT to access API endpoints.

SOCIALACCOUNT_PROVIDERS:

Configures Google OAuth settings for allauth.
'SCOPE': ['profile', 'email']: Requests the user’s name and email.
'AUTH_PARAMS': {'access_type': 'online'}: Ensures the OAuth flow is for online access (no refresh tokens needed).
MIDDLEWARE:
'allauth.account.middleware.AccountMiddleware': Required by django-allauth (version 0.53.0+) to manage user authentication flows, such as Google OAuth. It must come after AuthenticationMiddleware.

Migrate

Run migrations to apply these changes:

pipenv run python manage.py migrate

Troubleshooting

Error: allauth.account.middleware.AccountMiddleware missing:

If you see ImproperlyConfigured: allauth.account.middleware.AccountMiddleware must be added to settings.MIDDLEWARE, ensure you’re using django-allauth version 0.53.0 or higher (check with pipenv run pip show django-allauth). Add the middleware as shown above, after AuthenticationMiddleware.

Error: ModuleNotFoundError: No module named 'requests':

The requests library is required by allauth.socialaccount.providers.google to make HTTP requests to Google’s OAuth endpoints. Install it with:

pipenv install requests

Error: ModuleNotFoundError: No module named 'cryptography':

The cryptography library is required by allauth for secure JWT handling in Google OAuth. Install it with:

pipenv install cryptography

Configure the Google SocialApp in the Database

Before you can use Google OAuth, you need to configure a SocialApp in the database to store your Google OAuth credentials. django-allauth uses this to authenticate with Google.

Step 1. Create a Superuser:

To access the Django admin interface, create a superuser account:

pipenv run python manage.py createsuperuser

Follow the prompts to set a username, email, and password.

Step 2. Access the Admin Interface:
Start the server:

pipenv run python manage.py runserver

Visit http://localhost:8000/admin/ and log in with your superuser credentials.

Step 3. Add a Google SocialApp:

In the admin interface, under Social Accounts, click Social applications > Add social application.

Fill in the form:

Provider: Select "Google".
Name: Enter "Google OAuth".
Client ID: Enter the GOOGLE_CLIENT_ID from your .env file.
Secret key: Enter the GOOGLE_CLIENT_SECRET from your .env file.
Key: Leave blank.
Sites: Move the site with SITE_ID=1 (e.g., example.com) to the "Chosen sites" box.
Click Save.

This step ensures django-allauth can find the Google credentials when initiating the OAuth flow.

Task 3: Implement Backend Routes

We’ll set up routes for Google login, token issuance, and a sample /projects/ endpoint.

URLs

In ProjectAPI/urls.py:

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

urlpatterns = [
    path('admin/', admin.site.urls),
    path('auth/', include('allauth.urls')),
    path('api/', include('core.urls')),
]

In core/urls.py:

from django.urls import path
from . import views

urlpatterns = [
    path('', views.home, name='home'),
    path('token/', views.get_jwt_token, name='get_token'),
    path('projects/', views.projects, name='projects'),
]

Views
In core/views.py:

from django.shortcuts import render
from rest_framework.decorators import api_view, permission_classes
from rest_framework.permissions import IsAuthenticated
from rest_framework.response import Response
from rest_framework_simplejwt.tokens import RefreshToken

def home(request):
    return render(request, 'core/home.html')

@api_view(['GET'])
def get_jwt_token(request):
    if not request.user.is_authenticated:
        return Response({"error": "Please sign in first"}, status=401)
    refresh = RefreshToken.for_user(request.user)
    return Response({
        'refresh': str(refresh),
        'access': str(refresh.access_token),
    })

@api_view(['GET'])
@permission_classes([IsAuthenticated])
def projects(request):
    data = {
        "message": "Welcome to the project collaboration API!",
        "user": request.user.email,
        "projects": ["Sample Project 1", "Sample Project 2"]
    }
    return Response(data)

Custom Adapter

In core/adapters.py. Add:

from allauth.socialaccount.adapter import DefaultSocialAccountAdapter

class CustomSocialAccountAdapter(DefaultSocialAccountAdapter):
    def save_user(self, request, sociallogin, form=None):
        user = super().save_user(request, sociallogin, form)
        sociallogin.state['next'] = '/api/token/'
        return user

In settings.py. Add:

SOCIALACCOUNT_ADAPTER = 'core.adapters.CustomSocialAccountAdapter'

The custom adapter controls what happens after a user logs in with Google. Here’s what it does:

Why It’s Needed:

By default, after a Google login, django-allauth redirects the user to a default URL (e.g., /accounts/profile/) or a URL specified in the next parameter of the login request.
In an API app, you want the user to be redirected to /api/token/ to immediately obtain a JWT for API access, rather than a generic page.

How It Works:

CustomSocialAccountAdapter: This class inherits from DefaultSocialAccountAdapter, the default adapter for social logins in allauth.

save_user Method:

Called by allauth when a user logs in with Google to create or link a Django User.
super().save_user(request, sociallogin, form): Calls the default save_user method to handle user creation/linking.
sociallogin.state['next'] = '/api/token/': Sets the redirect URL to /api/token/ after login. The sociallogin.state dictionary is used by allauth to manage redirect state.

SOCIALACCOUNT_ADAPTER Setting:

Tells allauth to use your custom adapter (core.adapters.CustomSocialAccountAdapter) instead of the default one.

Role in the Flow:

After the user logs in with Google and is redirected back to /auth/google/callback/, allauth uses the custom adapter to set the redirect to /api/token/.
At /api/token/, the get_jwt_token view issues a JWT, which the user can use to access protected endpoints like /api/projects/.

Troubleshooting

Error: SocialApp.DoesNotExist:

If you see this error when trying to log in with Google, it means the Google SocialApp is not configured in the database. Ensure you’ve completed adding a Google SocialApp via the Django admin interface, including your GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.

Frontend

Create templates/core/:

home.html:


<!DOCTYPE html>
<html>
<head><title>Project Collaboration API</title></head>
<body>
  <h1>Sign In with Google</h1>
  {% if user.is_authenticated %}
    <p>Welcome, {{ user.first_name }}! <a href="/api/token/">Get JWT Token</a></p>
    <p><a href="/auth/logout/">Logout</a></p>
  {% else %}
    <p><a href="/auth/google/login/?process=login">Sign In with Google</a></p>
  {% endif %}
</body>
</html>

In settings.py:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'],
        'APP_DIRS': True,
        ...
    },
]

The Flow

Sign-In: /auth/google/login/ → Google → /auth/google/login/callback/.
Token: Redirects to/api/token/ for a JWT (thanks to the custom adapter).
API: Use the access token in Authorization: Bearer <token> for /api/projects/.

Testing the Authentication

Activate Pipenv:

pipenv shell

Run the server:

python manage.py runserver

Visit http://localhost:8000/api/, and sign in.

Get your JWT, and test /api/projects/:

curl -H "Authorization: Bearer <access_token>" http://localhost:8000/api/projects/

Conclusion

You’ve now added Google OAuth to a Django REST API, creating a seamless sign-in option that boosts user experience.

Summary

We Set up Google OAuth credentials.
Configured JWT for authenticated users.
Configured the Google SocialApp in the database.
Implemented backend routes for login and API access.
This foundation is ready for project collaboration features—expand it with your endpoints! Check out Django-Allauth Docs or DRF Docs for more.

What I Offer

Need a custom API solution? Here’s what I bring:

Custom Django REST APIs: Secure, scalable backends tailored to your needs.
Fast API Development: Using DRF and GraphQL for rapid builds.
Authentication & Security: JWT, OAuth2, rate limiting, CORS, API keys.
Database Optimization: Tuning PostgreSQL, MySQL, Redis, or MongoDB.
Third-Party API Integrations: Stripe, Twilio, OpenAI, Zapier, Google Maps, and more.
Real-time Features: WebSockets and Celery for dynamic apps.
Comprehensive API Documentation: Swagger, OpenAPI, or Postman for clarity.
Let’s build something amazing together!

How to Build a Task Manager API with Django REST Framework: Part 7 - API Documentation with OpenAPI and Swagger

kihuni — Wed, 19 Mar 2025 06:47:15 +0000

Welcome back, to our Django REST Framework (DRF) series! Over the past six parts, we’ve built a Task Manager API using Django REST Framework (DRF)

Part 1: we set up Django and DRF.
Part 2: added CRUD operations for tasks.
Part 3: secured it with token authentication.
Part 4: personalized it with user-owned tasks.
Part 5: optimized it with filtering, pagination, and search.
Part 6: locked it down with security best practices like rate limiting, CORS, and HTTPS readiness.

Now, in Part 7—the final part of this series—we’ll make our API developer-friendly by adding interactive API documentation using OpenAPI and Swagger ui. By the end, you’ll have an API with documentation that developers can use to understand and test your endpoints interactively.

Why API Documentation Matters
Step 1: Install drf-spectacular
Step 2: Configure drf-spectacular in Settings
Step 3: Set Up Swagger UI
Step 4: Enhance Documentation with Descriptions
Step 5: Test the Interactive Documentation
Conclusion
What’s Next?

Why API Documentation Matters

API documentation is a bridge between your API and its users (developers). Good documentation:

Explains what each endpoint does, its parameters, and expected responses.
Reduces the learning curve for developers integrating with your API.
Provides an interactive interface (via Swagger UI) for testing endpoints without external tools like Postman.
Builds trust by making your API professional and transparent.

We’ll use OpenAPI (a standard for API specifications) and Swagger UI (a tool to visualize and interact with the API) to generate our documentation. The drf-spectacular library will help us create an OpenAPI schema for our DRF API and integrate Swagger UI seamlessly.

Step 1: Install drf-spectacular

drf-spectacular is a library for generating OpenAPI schemas with DRF. It’s well-maintained and supports advanced features like schema customization.

Install the Package
In your project directory, activate your virtual environment (if not already activated) and install drf-spectacular:

pip install drf-spectacular

Add it to your INSTALLED_APPS in taskmanager/settings.py:

INSTALLED_APPS = [
    ...

    'drf_spectacular',  # Add drf-spectacular for OpenAPI schema generation
    ...
]

Step 2: Configure drf-spectacular in Settings

Let’s configure drf-spectacular to generate an OpenAPI schema for our API. We’ll also set it as the default schema generator for DRF.

Update taskmanager/settings.py
Add the following to your REST_FRAMEWORK settings:

REST_FRAMEWORK = {
...

# Use drf-spectacular for schema generation
'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',

...
}

Add drf-spectacular settings to customize the API documentation:

SPECTACULAR_SETTINGS = {
    'TITLE': 'Task Manager API',
    'DESCRIPTION': 'A RESTful API for managing tasks, built with Django REST Framework. Features include CRUD operations, user authentication, filtering, pagination, search, and security best practices.',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': True,  # Include the schema in the Swagger UI
    'SWAGGER_UI_SETTINGS': {
        'deepLinking': True,
        'displayOperationId': True,
        'defaultModelsExpandDepth': 1,
        'defaultModelExpandDepth': 1,
    },
}

'DEFAULT_SCHEMA_CLASS': Tells DRF to use drf-spectacular’s schema generator instead of the default.
SPECTACULAR_SETTINGS:
- TITLE, DESCRIPTION, and VERSION define metadata for your API.
- SERVE_INCLUDE_SCHEMA: Ensures the OpenAPI schema is accessible via Swagger UI.
- SWAGGER_UI_SETTINGS: Customizes the Swagger UI interface for better usability.

Step 3: Set Up Swagger UI

drf-spectacular provides built-in views for Swagger UI, Redoc (another documentation UI), and the raw OpenAPI schema. We’ll set up Swagger UI to provide an interactive interface for testing our API.

Update taskmanager/urls.py
Modify your project’s URL configuration to include drf-spectacular’s views:

from django.contrib import admin
from django.urls import path, include
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('tasks.urls')),  # Your existing API routes
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),  # Endpoint for the OpenAPI schema
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),  # Swagger UI
]

SpectacularAPIView: Provides the raw OpenAPI schema at /api/schema/.
SpectacularSwaggerView: Renders the Swagger UI at /api/docs/, using the schema from /api/schema/.

Step 4: Enhance Documentation with Descriptions

To make the documentation more informative, let’s add descriptions to our serializers and views using drf-spectacular’s @extend_schema decorator. This step is optional but recommended for clarity.

Update tasks/serializers.py
Add a docstring to the TaskSerializer to provide a description that will appear in the OpenAPI schema:

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

User = get_user_model()

class LoginSerializer(serializers.Serializer):
    """Serializer for login credentials."""
    username = serializers.CharField(max_length=150)
    password = serializers.CharField(max_length=128, write_only=True)

class TokenSerializer(serializers.Serializer):
    """Serializer for the token response."""
    token = serializers.CharField()

class TaskSerializer(serializers.ModelSerializer):
    """Serializer for Task objects, including validation for the title field."""
    class Meta:
        model = Task
        fields = ['id', 'title', 'description', 'completed', 'created_at', 'created_by']
        read_only_fields = ['id', 'created_at', 'created_by']

    def validate_title(self, value):
        if len(value) < 3:
            raise serializers.ValidationError("Title must be at least 3 characters long.")
        if not value.replace(' ', '').isalnum():
            raise serializers.ValidationError("Title must be alphanumeric with optional spaces.")
        return value

class UserSerializer(serializers.ModelSerializer):
    """Serializer for User objects during registration."""
    class Meta:
        model = User
        fields = ['id', 'username', 'password']
        extra_kwargs = {'password': {'write_only': True}}

    def create(self, validated_data):
        user = User.objects.create_user(**validated_data)
        return user

The docstring (Serializer for Task objects, including validation for the title field.) will be used by drf-spectacular as the serializer’s description in the OpenAPI schema.

Update tasks/views.py
Add descriptions to the views using @extend_schema:

from rest_framework import generics, views
from .models import Task
from .serializers import TaskSerializer, UserSerializer, LoginSerializer, TokenSerializer
from django.contrib.auth import authenticate
from rest_framework.permissions import IsAuthenticated, AllowAny
from rest_framework.authentication import TokenAuthentication
from rest_framework.authtoken.models import Token
from rest_framework.response import Response
from rest_framework import status
from django_filters.rest_framework import DjangoFilterBackend
from rest_framework.pagination import PageNumberPagination
from rest_framework.filters import SearchFilter
from .pagination import CustomPageNumberPagination
from drf_spectacular.utils import extend_schema, OpenApiResponse

class RegisterView(views.APIView):
    permission_classes = [AllowAny]
    serializer_class = UserSerializer

    @extend_schema(
        summary="Register a new user",
        description="Create a new user account. Requires a username and password in the request body.",
        request=UserSerializer,
        responses={
            201: OpenApiResponse(response=TokenSerializer, description="User created successfully"),
            400: OpenApiResponse(description="Invalid data"),
        },
    )
    def post(self, request):
        serializer = UserSerializer(data=request.data)
        if serializer.is_valid():
            user = serializer.save()
            token, _ = Token.objects.get_or_create(user=user)
            return Response({'token': token.key}, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

class LoginView(views.APIView):
    permission_classes = [AllowAny]
    serializer_class = LoginSerializer

    @extend_schema(
        summary="Login to get a token",
        description="Authenticate a user and return a token. Requires username and password.",
        request=LoginSerializer,
        responses={
            200: OpenApiResponse(response=TokenSerializer, description="Token retrieved successfully"),
            400: OpenApiResponse(description="Invalid credentials"),
        },
    )
    def post(self, request):
        serializer = LoginSerializer(data=request.data)
        if serializer.is_valid():
            username = serializer.validated_data['username']
            password = serializer.validated_data['password']
            user = authenticate(username=username, password=password)
            if user:
                token, _ = Token.objects.get_or_create(user=user)
                return Response({'token': token.key}, status=status.HTTP_200_OK)
        return Response({'error': 'Invalid Credentials'}, status=status.HTTP_400_BAD_REQUEST)

@extend_schema(
    summary="List or create tasks",
    description="Retrieve a paginated list of tasks for the authenticated user or create a new task. Supports filtering by completed status (e.g., ?completed=true) and search by title (e.g., ?search=urgent). The title must be at least 3 characters long and alphanumeric (spaces allowed) when creating a task.",
)
class TaskListCreateView(generics.ListCreateAPIView):
    serializer_class = TaskSerializer
    permission_classes = [IsAuthenticated]
    authentication_classes = [TokenAuthentication]
    filter_backends = [DjangoFilterBackend, SearchFilter]
    filterset_fields = ['completed']
    search_fields = ['title']
    pagination_class = CustomPageNumberPagination

    def get_queryset(self):
        if getattr(self, "swagger_fake_view", False):  # Handle schema generation
            return Task.objects.none()  # Return empty queryset for schema generation
        return Task.objects.filter(created_by=self.request.user).order_by('-created_at')

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

@extend_schema(
    summary="Retrieve, update, or delete a task",
    description="Retrieve, update, or delete a specific task by ID, if it belongs to the authenticated user.",
)
class TaskDetailView(generics.RetrieveUpdateDestroyAPIView):
    serializer_class = TaskSerializer
    permission_classes = [IsAuthenticated]
    authentication_classes = [TokenAuthentication]

    def get_queryset(self):
        return Task.objects.filter(created_by=self.request.user)

The @extend_schema decorators provide summaries and descriptions for the combined actions of each generic view, aligning with your implementation.

Step 5: Test the Interactive Documentation

Let’s access the Swagger UI and test our API endpoints interactively.

Start the Server
Ensure your server is running:

python manage.py runserver

Access Swagger UI
Open your browser and navigate to:

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

You should see the Swagger UI interface with the title Task Manager API and a description matching what you set in SPECTACULAR_SETTINGS.

1. Test an Endpoint
Authenticate:

Use the http://127.0.0.1:8000/api/login/ endpoint to get a token:
Click on POST /api/login/.
Click Try it out.

In the request body, enter:

{
    "username": "user1",
    "password": "pass123"
}

Click Execute.

Copy the token from the response (e.g., token1).

Authorize Swagger UI:
Click the Authorize button (top right).

Enter Token (e.g., Token token1) in the Value field and click Authorize.

2. List Tasks:
Go to GET /api/tasks/.

Click Try it out and Execute.

Expect a 200 OK response with a paginated list of tasks for the authenticated user.

3. Create a Task:
Go to POST /api/tasks/.

Click Try it out.

Enter a task in the request body:

{
    "title": "New Task",
    "description": "This is a test task.",
    "completed": false
}

Click Execute.

Expect a 201 Created response with the new task’s details.

4. Get a Task:
Go to GET /api/tasks/{id}/.

Add query ID (e.g., 6).

Click Execute.

Conclusion

Congratulations! You’ve built a fully functional, secure, well-documented Task Manager API with Django REST Framework! Over this series, you’ve learned how to:

Set up a Django project with DRF (Part 1).
Implement CRUD operations for tasks (Part 2).
Secure the API with token authentication (Part 3).
Personalize tasks for users using generic views (Part 4).
Optimize with filtering, pagination, and search (Part 5).
Add security best practices like rate limiting and HTTPS (Part 6).
Generate interactive API documentation with OpenAPI and Swagger (Part 7).

Summary

Installed drf-spectacular
Configured OpenAPI schema generation
Set up Swagger UI
Enhanced documentation with descriptions for generic views
Tested the interactive documentation

What’s Next?

This series has ended, but your journey as an API developer is just beginning! Here are some ideas to take your Task Manager API to the next level:

Deploy to Production: Deploy your API on a platform like Render, Heroku, or AWS. Use a production-grade server like Gunicorn with Nginx, and enable HTTPS with a free SSL certificate from Let’s Encrypt.
Add More Features: Implement task categories, due dates, or reminders. Add email notifications for task updates using Django’s email backend.
Build a Frontend: Create a frontend using React, Vue.js, or Angular to consume your API and provide a user-friendly interface for managing tasks.
Explore Advanced DRF Features: Dive into DRF’s advanced features like custom permissions, nested serializers, or WebSocket support for real-time updates.

Thank you for following along with this series! I hope you’ve enjoyed building this API as much as I’ve enjoyed guiding you through it.

Loved this series? Share your feedback, questions, or what you’d like to see next in the comments below

Forem: kihuni

My Journey Contributing to Django: From Intimidation to a Merged Ticket 🚀

Contributing to Django felt intimidating at first.

Djangonaut Space

The Ticket That Changed Everything

What This Journey Taught Me

🙏 Acknowledgements & Thanks

Learn URLs in Django: From Setup to Dynamic Routing

Getting Django Set Up

URL configuration in Django

Dynamic Paths with Converters

Regular Expression Paths

Grouping Related URLs

Naming URLs

Wrapping Up

The Big Picture

How the Web Talks to Django: A Beginner's Guide

Learn how your keystrokes in the browser turn into responses from Django.

How the Web Works

What is DNS (Domain Name System)?

HTTP — The Language of the Web

When the Request Finally Reaches Django

How to Send Emails with Django: A Simple Guide

Who Should Read This?

Configure Email Settings in Django

How to Build a Payment Gateway with Django and PayPal: A Step-by-Step Guide

Why Build a Payment Gateway?

What You’ll Need

How to Get PayPal Credentials

Step-by-Step Guide

Step 2. Define the Data Model

Step 3. Build the API

payments/serializers.py

payments/urls.py

Step 5. Deploy with CI/CD

6. Common Pitfalls & Fixes

7. Test It Out!

Conclusion

`Lets-Collab`: Building a Secure Collaboration Platform with Django, React, and Permit.io

What I Built

Demo

Project Repo

My Journey

API-First Authorization

Conclusion

Build Your First Blog with Django: Part 1 - Setting Up Your Development Environment

Table of Contents

Prerequisites

What is Django?

Why Use Django for a Blog App?

Setting Up the Development Environment

Step 1: Install Python

Step 2: Create a Virtual Environment

Step 3: Install Django

Step 4: Create a Django Project

Step 5: Run the Development Server

What’s Next?

Building a Secure JWT Authentication System with Django

Why Choose JWT for Shopease-API?

The Authentication Flow

Step-by-Step Implementation

Key Features in Action

Lessons Learned

Understanding Authentication with JWT and Registration with Email Verification: A Case Study with LiveStatusAPI

What is JWT Authentication?

Understanding JWT

How JWT Authentication Works

Why Use JWT?

What is Registration with Email Verification?

The Importance of Email Verification

Why Use Email Verification?

Implementing JWT Authentication and Email Verification in Django

Understanding the Email Settings in Django

Setting Up Gmail for Sending Emails

Case Study: Applying JWT Authentication and Email Verification to LiveStatusAPI

Conclusion

Secure Image Processing with Pulumi ESC, Clarifai, and pCloud

What I Built

Live Demo Link

Project Repo