Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 39 ยท Getting Started

Project Setup and the REST_FRAMEWORK Settings

Set up a Django REST Framework project, add rest_framework to INSTALLED_APPS, and learn the REST_FRAMEWORK settings dictionary that controls every view's defaults.

Every DRF project starts the same way: install the package, add it to INSTALLED_APPS, wire up a URL file and decide on defaults. The defaults live in one place, a dictionary called REST_FRAMEWORK in your Django settings. Once you know what it can hold, you can change how every endpoint authenticates, paginates, parses and renders without touching a single view.

This lesson walks through the setup commands, a sensible starting settings.py, how DRF reads those settings, and how a view can override them one at a time.

The setup, step by step

On your own machine you would run these commands in a virtual environment:

Terminal
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install django djangorestframework
django-admin startproject shop .
python manage.py startapp catalog

Then register the packages in shop/settings.py:

Python
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "rest_framework",   # DRF itself
    "catalog",          # your app
]

rest_framework must be in the list because it ships templates (the browsable API) and static files, and Django only finds those for installed apps. Plain JSON endpoints would work without it, but the HTML pages and the login form would not.

The project's urls.py then includes your app's URLs:

Python
from django.urls import include, path

urlpatterns = [
    path("api/", include("catalog.urls")),
    path("api-auth/", include("rest_framework.urls")),  # login/logout for the browsable API
]

The api-auth/ line is optional. It adds a login and logout page so that you can sign in from the browsable API in a browser.

The REST_FRAMEWORK dictionary

DRF reads its configuration from settings.REST_FRAMEWORK. Every key is optional. A realistic first version looks like this:

Python
REST_FRAMEWORK = {
    "DEFAULT_RENDERER_CLASSES": [
        "rest_framework.renderers.JSONRenderer",
        "rest_framework.renderers.BrowsableAPIRenderer",
    ],
    "DEFAULT_PARSER_CLASSES": [
        "rest_framework.parsers.JSONParser",
    ],
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework.authentication.SessionAuthentication",
    ],
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticatedOrReadOnly",
    ],
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
    "PAGE_SIZE": 20,
    "DEFAULT_THROTTLE_RATES": {"anon": "100/hour", "user": "1000/hour"},
}

Keys fall into families:

Family Example keys Covered in
Parsing and rendering DEFAULT_PARSER_CLASSES, DEFAULT_RENDERER_CLASSES Parsers, Renderers and Content Negotiation
Security DEFAULT_AUTHENTICATION_CLASSES, DEFAULT_PERMISSION_CLASSES, DEFAULT_THROTTLE_* Authentication Schemes, Permission Classes
Lists DEFAULT_PAGINATION_CLASS, PAGE_SIZE, DEFAULT_FILTER_BACKENDS later chapters
Formats DATETIME_FORMAT, COERCE_DECIMAL_TO_STRING, DATE_INPUT_FORMATS Serializer Fields
Errors EXCEPTION_HANDLER, NON_FIELD_ERRORS_KEY Exception Handling

Reading the settings from code

DRF wraps the dictionary in an object called api_settings. It returns your value when you set one and DRF's own default otherwise, and it imports dotted class paths for you. The code below configures a project, then reads defaults and overrides back.

Python api_settings: defaults and overrides

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that PAGE_SIZE is None by default: nothing is paginated until you choose a pagination class and a size. Also notice that the default permission is AllowAny. A fresh DRF project is completely open. The first thing a real project does is tighten DEFAULT_PERMISSION_CLASSES.

api_settings.reload() exists for tests and demos. In a real project DRF reads REST_FRAMEWORK once, at first use, and you never need to call it. Changing settings at runtime in production code is a bug waiting to happen.

Overriding the defaults per view

Global settings are the baseline. Any view can replace them with class attributes, and a function view can use decorators.

Python A per-view override wins over settings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Anonymous callers get 403 Forbidden on the private endpoint because the global default is IsAuthenticated, but the public view declared its own permission_classes and ignored the default. Schemes that can send a WWW-Authenticate header produce 401 instead of 403, which you will meet in Authentication Schemes.

For class-based views the same idea is a class attribute (permission_classes = [AllowAny]). Decorators and attributes replace the default list completely; they do not merge with it.

A settings checklist for a new project

  1. Add rest_framework to INSTALLED_APPS.
  2. Set DEFAULT_PERMISSION_CLASSES to something stricter than AllowAny.
  3. Choose authentication classes that match your clients (sessions for browsers, tokens or JWT for apps).
  4. Turn on a pagination class early. Adding it later changes the shape of every list response and breaks clients.
  5. Keep the browsable API renderer in development; many teams remove it in production to shrink the attack surface.
  6. Move secrets and DEBUG out of settings.py into environment variables.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does DRF read its global configuration from?

    All global defaults live in the REST_FRAMEWORK dictionary in settings.py; keys you omit fall back to DRF's own defaults.
  2. 2. What is DRF's default permission class when you configure nothing?

    A fresh project is open to everyone (AllowAny). Setting DEFAULT_PERMISSION_CLASSES is one of the first hardening steps.
  3. 3. A view sets permission_classes = [AllowAny] while the global default is IsAuthenticated. What happens?

    Per-view settings replace the global value; they are not merged.
  4. 4. Why does the project need rest_framework in INSTALLED_APPS?

    Django discovers app templates and static files from installed apps, which the browsable API needs.

Summary

  • Install djangorestframework, add rest_framework to INSTALLED_APPS and include your URLs.
  • REST_FRAMEWORK in settings sets defaults for parsers, renderers, authentication, permissions, throttling, pagination and more.
  • api_settings reads those values with DRF's defaults as fallback.
  • By default nothing is paginated and everything is open (AllowAny).
  • Class attributes and decorators override a default for one view, replacing rather than merging.

Next: Exception Handling