🔗 Connecting Python Backends to React

Decoupled Architecture

In a decoupled (or "headless") architecture, the frontend and backend are separate applications. React owns the browser UI; Python owns the data and business logic. They meet at a single, well-defined boundary: an HTTP + JSON API.

Real-world analogy: a restaurant with a kitchen (backend) and a dining room (frontend), connected by waitstaff (the API). The kitchen doesn't care how tables are arranged, and diners don't need to see the stove — the waitstaff carry a clear, agreed-upon interface between them.

Configuring CORS

Because React (say, http://localhost:3000) and your API (http://localhost:8000) live on different origins, the browser's same-origin policy blocks the requests unless the server explicitly opts in with CORS (Cross-Origin Resource Sharing) headers.

Django

pip install django-cors-headers

# settings.py
INSTALLED_APPS = [
    # ...
    "corsheaders",
]

MIDDLEWARE = [
    "corsheaders.middleware.CorsMiddleware",   # as high as possible
    "django.middleware.common.CommonMiddleware",
    # ... the rest
]

# Be specific — never open to every origin in production.
CORS_ALLOWED_ORIGINS = [
    "http://localhost:3000",
    "https://yourdomain.com",
]
CORS_ALLOW_CREDENTIALS = True   # only if you use cookies

Flask

# pip install flask-cors
from flask import Flask
from flask_cors import CORS

app = Flask(__name__)
CORS(app, resources={r"/api/*": {"origins": "http://localhost:3000"}})

The JWT Auth Flow

For decoupled apps, JWT (JSON Web Token) authentication is the common choice. The client logs in once, receives a short-lived access token and a longer-lived refresh token, then attaches the access token to each request. When it expires, the refresh token quietly mints a new one.

Backend (Django + Simple JWT)

pip install djangorestframework-simplejwt

# settings.py
REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework_simplejwt.authentication.JWTAuthentication",
    ],
}

# urls.py
from rest_framework_simplejwt.views import (
    TokenObtainPairView, TokenRefreshView,
)

urlpatterns += [
    path("api/token/", TokenObtainPairView.as_view(), name="token_obtain_pair"),
    path("api/token/refresh/", TokenRefreshView.as_view(), name="token_refresh"),
]

Frontend auth helper

// auth.js
import axios from "axios";

const API = "http://localhost:8000/api";

export async function login(username, password) {
  const { data } = await axios.post(`${API}/token/`, { username, password });
  localStorage.setItem("access", data.access);
  localStorage.setItem("refresh", data.refresh);
}

export function logout() {
  localStorage.removeItem("access");
  localStorage.removeItem("refresh");
}

export async function refreshAccessToken() {
  const refresh = localStorage.getItem("refresh");
  const { data } = await axios.post(`${API}/token/refresh/`, { refresh });
  localStorage.setItem("access", data.access);
  return data.access;
}

export const isAuthenticated = () => Boolean(localStorage.getItem("access"));

A Reusable Axios Client

Rather than repeat headers and error handling in every call, create one configured Axios instance. Interceptors let you attach the token to every outgoing request and react to auth failures on every response — including transparently refreshing an expired access token.

// api/client.js
import axios from "axios";
import { refreshAccessToken, logout } from "../auth";

const apiClient = axios.create({
  baseURL: "http://localhost:8000/api",
  headers: { "Content-Type": "application/json" },
});

// Request: attach the access token if we have one.
apiClient.interceptors.request.use((config) => {
  const token = localStorage.getItem("access");
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

// Response: on a 401, try one silent refresh, then retry the request.
apiClient.interceptors.response.use(
  (response) => response,
  async (error) => {
    const original = error.config;
    if (error.response?.status === 401 && !original._retried) {
      original._retried = true;
      try {
        const newToken = await refreshAccessToken();
        original.headers.Authorization = `Bearer ${newToken}`;
        return apiClient(original);        // replay the original request
      } catch {
        logout();
        window.location.assign("/login");  // refresh failed — start over
      }
    }
    return Promise.reject(error);
  }
);

export default apiClient;

API Service Modules

Group related endpoints into small service modules. Components import a service instead of talking to Axios directly, so if a URL changes you fix it in one place.

// api/bookService.js
import apiClient from "./client";

const bookService = {
  list: (params) => apiClient.get("/books/", { params }),
  get: (id) => apiClient.get(`/books/${id}/`),
  create: (data) => apiClient.post("/books/", data),
  update: (id, data) => apiClient.put(`/books/${id}/`, data),
  remove: (id) => apiClient.delete(`/books/${id}/`),
};

export default bookService;

A first pass at consuming it with plain hooks looks like this — functional, but note how much boilerplate loading/error state it needs:

// components/BookList.jsx
import { useState, useEffect } from "react";
import bookService from "../api/bookService";

export default function BookList() {
  const [books, setBooks] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    bookService
      .list()
      .then((res) => setBooks(res.data.results ?? res.data))
      .catch(() => setError("Failed to load books"))
      .finally(() => setLoading(false));
  }, []);

  if (loading) return <p>Loading…</p>;
  if (error) return <p role="alert">{error}</p>;

  return (
    <ul>
      {books.map((b) => (
        <li key={b.id}>{b.title} — {b.author}</li>
      ))}
    </ul>
  );
}

Managing Server State

Data from an API isn't ordinary UI state — it lives on the server, can go stale, and needs caching, refetching, and deduplication. Hand-rolling all that with useState/useEffect gets repetitive fast. React Query (TanStack Query) was built exactly for this.

Setup

npm install @tanstack/react-query

// main.jsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import App from "./App";

const queryClient = new QueryClient();

export default function Root() {
  return (
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  );
}

Reading data with useQuery

// hooks/useBooks.js
import { useQuery } from "@tanstack/react-query";
import bookService from "../api/bookService";

export function useBooks() {
  return useQuery({
    queryKey: ["books"],
    queryFn: async () => {
      const res = await bookService.list();
      return res.data.results ?? res.data;
    },
  });
}

// components/BookList.jsx
import { useBooks } from "../hooks/useBooks";

export default function BookList() {
  const { data: books, isLoading, isError } = useBooks();

  if (isLoading) return <p>Loading…</p>;
  if (isError) return <p role="alert">Failed to load books</p>;

  return (
    <ul>
      {books.map((b) => (
        <li key={b.id}>{b.title}</li>
      ))}
    </ul>
  );
}

Writing data with useMutation

After a create/update/delete, invalidate the cached query so the list refetches and stays in sync automatically:

// hooks/useCreateBook.js
import { useMutation, useQueryClient } from "@tanstack/react-query";
import bookService from "../api/bookService";

export function useCreateBook() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data) => bookService.create(data),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["books"] }),
  });
}

// components/BookForm.jsx
import { useState } from "react";
import { useCreateBook } from "../hooks/useCreateBook";

export default function BookForm() {
  const [title, setTitle] = useState("");
  const createBook = useCreateBook();

  function handleSubmit(e) {
    e.preventDefault();
    createBook.mutate({ title }, { onSuccess: () => setTitle("") });
  }

  return (
    <form onSubmit={handleSubmit}>
      <input value={title} onChange={(e) => setTitle(e.target.value)} />
      <button type="submit" disabled={createBook.isPending}>
        {createBook.isPending ? "Adding…" : "Add book"}
      </button>
    </form>
  );
}

Hands-on Exercise

// api/taskService.js
import apiClient from "./client";

const taskService = {
  list: () => apiClient.get("/tasks/"),
  create: (data) => apiClient.post("/tasks/", data),
};
export default taskService;

// hooks/useTasks.js
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import taskService from "../api/taskService";

export function useTasks() {
  return useQuery({
    queryKey: ["tasks"],
    queryFn: async () => {
      const res = await taskService.list();
      return res.data.results ?? res.data;
    },
  });
}

export function useCreateTask() {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (data) => taskService.create(data),
    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["tasks"] }),
  });
}

// components/TaskList.jsx
import { useState } from "react";
import { useTasks, useCreateTask } from "../hooks/useTasks";

export default function TaskList() {
  const { data: tasks, isLoading, isError } = useTasks();
  const createTask = useCreateTask();
  const [title, setTitle] = useState("");

  if (isLoading) return <p>Loading…</p>;
  if (isError) return <p role="alert">Could not load tasks</p>;

  return (
    <div>
      <ul>
        {tasks.map((t) => (
          <li key={t.id}>{t.title}</li>
        ))}
      </ul>
      <form
        onSubmit={(e) => {
          e.preventDefault();
          createTask.mutate({ title }, { onSuccess: () => setTitle("") });
        }}
      >
        <input value={title} onChange={(e) => setTitle(e.target.value)} />
        <button disabled={createTask.isPending}>Add</button>
      </form>
    </div>
  );
}

Best Practices

Deployment at a glance

Two common shapes: deploy the two apps separately (React on a static host like Netlify/Vercel, the API on a server), or build React and let the Python app serve the static files. Separate deployment scales each side independently but requires CORS and possibly a custom domain; single-server deployment is simpler to reason about but couples releases.

Summary & Quiz

📚 Further Reading

• TanStack Query (React Query) docs
• djangorestframework-simplejwt
• django-cors-headers
• MDN — Cross-Origin Resource Sharing (CORS)

🚀 What's Next?

You've closed the loop from database to browser. Next you'll put all three lessons together in the Weekend Project: Python Web Frameworks, building a complete full-stack app end to end.