Django REST Framework PostgreSQL CRUD API Starter

A Django 6.1 and Django REST framework 3.18 CRUD API starter in Python 3.12 that stores one resource, items, in PostgreSQL through the Django ORM and psycopg 3, served by Gunicorn. It is for Python developers who want a model, a serializer and a ModelViewSet already wired up, with a migration, limit and offset paging, JSON errors, a database health check and tests.

by Light CloudCRUD APIs

Features

  • GET /items?limit=20&offset=0 lists items oldest first; a limit outside 1 to 100 or a negative offset answers 400
  • One ModelViewSet handles get, create, replace and delete, routed by SimpleRouter without trailing slashes
  • The serializer trims name, keeps it to 1 to 200 characters and rejects a number instead of turning it into text
  • Every error is { "error": "..." }: 400 for bad input, 404 for an unknown item or route, 405 for PATCH
  • Migration 0001_initial creates the items table, and config/wsgi.py runs migrate on every start
  • GET /health runs SELECT 1 and answers 200, or 503 with { "error": "Database unavailable" }
  • Persistent connections (CONN_MAX_AGE=60) with health checks, and TLS to the database by default (DB_SSLMODE=require)
  • Tests for CRUD, paging, validation, health and 404s with Django's test runner on a real PostgreSQL; ruff for linting

Tech stack

What you need

  • A paid plan: deploying creates a PostgreSQL database, which the Free plan does not include
  • To run it locally: Python 3.12 with pip, and Docker for a local PostgreSQL
  • No API keys: it starts with nothing to configure
  • Optional: DJANGO_SECRET_KEY; without it a random signing key is made at each start, which this API has no need to keep
  • Outside Light Cloud: a PostgreSQL database set through DB_HOST, DB_NAME, DB_USER and DB_PASSWORD, with DB_SSLMODE=disable if it has no TLS

About

The project is cut down to what a JSON API needs: INSTALLED_APPS holds only rest_framework and items, the middleware list is empty, and DRF renders and parses JSON only, so there is no admin, browsable API or template setup. config/exceptions.py reshapes every DRF error into a single error string, and config/wsgi.py applies migrations before Gunicorn takes traffic, so an unreachable database shows up at deploy time rather than on the first request. The first change is usually renaming Item or giving it your own fields, then running makemigrations and committing the migration. On Light Cloud the deploy runs gunicorn config.wsgi:application with 4 threads on the PORT the platform sets, with the DB_* variables filled in, and every push to your copy redeploys.

FAQ

How do I deploy a Django REST API with a PostgreSQL database?

Press Deploy on this template's page: Light Cloud copies the repo into your GitHub account, creates a PostgreSQL database and sets DB_HOST, DB_NAME, DB_USER and DB_PASSWORD on the app. Databases need a paid plan.

How do I add a field to a Django REST framework model?

Add it to Item in items/models.py and to fields in items/serializers.py, then run python manage.py makemigrations and commit the new migration. It is applied the next time the app starts, locally and on deploy.

How do I add a new resource in Django REST framework?

Run python manage.py startapp things and give it a model, a serializer and a viewset modelled on items/. Add the app to INSTALLED_APPS in config/settings.py, include its urls in config/urls.py and run makemigrations.

Does this Django API have Swagger or OpenAPI docs?

No. It renders JSON only and DRF's browsable API is off. drf-spectacular adds an OpenAPI schema and Swagger UI, but it needs Django's TEMPLATES setting and django.contrib.staticfiles added to config/settings.py first.

Can I host this Django API without Light Cloud?

Yes. Any host with Python 3.12 and a PostgreSQL database runs it: install requirements.txt, set the DB_* variables and start gunicorn config.wsgi:application --bind 0.0.0.0:$PORT. Migrations run on start, so there is no release step.

Price
Free
Framework
Django · Python
Updated