Django REST Framework JSON:API

8.1.0 · active · verified Thu Apr 16

DRF JSON:API is a Django REST framework API adapter for the JSON:API specification. It simplifies building APIs that adhere to the JSON:API standard, providing serializers, parsers, and renderers. The current version is 8.1.0, and new major versions are released roughly every 3-6 months, with patch releases as needed.

Common errors

Warnings

Install

Imports

Quickstart

This quickstart demonstrates how to set up a basic JSON:API compliant endpoint for a `Post` model. It defines a Django model, a `djangorestframework-jsonapi` serializer, and a viewset, then registers it with DRF's router. Remember to configure DRF's renderer, parser, and metadata classes in your `settings.py`.

import os
from django.db import models
from rest_framework_json_api import serializers, views
from rest_framework import routers
from django.urls import path, include
from django.conf import settings

# Minimal Django settings for quickstart
if not settings.configured:
    settings.configure(
        DEBUG=True,
        INSTALLED_APPS=[
            'django.contrib.auth',
            'django.contrib.contenttypes',
            'rest_framework',
            'rest_framework_json_api',
            'quickstart_app' # A dummy app for models/serializers
        ],
        ROOT_URLCONF=__name__,
        REST_FRAMEWORK = {
            'DEFAULT_RENDERER_CLASSES': (
                'rest_framework_json_api.renderers.JSONRenderer',
                'rest_framework.renderers.BrowsableAPIRenderer', # Optional for browsable API
            ),
            'DEFAULT_PARSER_CLASSES': (
                'rest_framework_json_api.parsers.JSONParser',
            ),
            'DEFAULT_METADATA_CLASS': 'rest_framework_json_api.metadata.JSONAPIMetadata',
            'DEFAULT_FILTER_BACKENDS': (
                'rest_framework_json_api.filters.QueryParameterValidationFilter',
                'rest_framework_json_api.filters.OrderingFilter',
                'rest_framework_json_api.django_filters.DjangoFilterBackend',
                'rest_framework.filters.SearchFilter',
            ),
            'SEARCH_PARAM': 'filter[search]',
            'TEST_REQUEST_RENDERER_CLASSES': (
                'rest_framework_json_api.renderers.JSONRenderer',
            ),
            'TEST_REQUEST_PARSER_CLASSES': (
                'rest_framework_json_api.parsers.JSONParser',
            )
        }
    )

# 1. Define a simple Django Model
class Post(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.title

# 2. Define a JSON:API Serializer for the Model
class PostSerializer(serializers.ModelSerializer):
    class Meta:
        model = Post
        fields = ('id', 'title', 'content', 'created_at')
        json_api_type = 'posts'

# 3. Define a JSON:API ViewSet
class PostViewSet(views.ModelViewSet):
    queryset = Post.objects.all()
    serializer_class = PostSerializer
    # Filtering, ordering, search can be enabled via DRF settings and filter backends

# 4. Register the ViewSet with a Router
router = routers.DefaultRouter()
router.register(r'posts', PostViewSet)

# 5. Define URL patterns
urlpatterns = [
    path('', include(router.urls)),
]

# To run this example (requires Django and DRF installed):
# 1. Create a quickstart_app directory with an __init__.py inside your Django project
# 2. Add 'quickstart_app' to INSTALLED_APPS in settings.py
# 3. Add 'path('api/', include(router.urls))' to your project's urls.py
# 4. python manage.py makemigrations quickstart_app
# 5. python manage.py migrate
# 6. python manage.py createsuperuser (optional)
# 7. python manage.py runserver
# Then visit http://127.0.0.1:8000/posts/ or use a tool like Postman with Accept: application/vnd.api+json

view raw JSON →