Django REST framework JSON:API

DJA pagination follows DRF patterns and returns a meta object with record counts and a links object for navigation. You can set pagination globally in REST_FRAMEWORK['DEFAULT_PAGINATION_CLASS'] or per viewset using the pagination_class attribute.

JsonApiPageNumberPagination

Breaks responses into pages based on a page number.

• page_query_param (default: page[number])
• page_size_query_param (default: page[size]). Set to None to disable client-side size selection.
• page_size (default: REST_FRAMEWORK['PAGE_SIZE'])
• max_page_size (default: 100)

JsonApiLimitOffsetPagination

Breaks responses into pages based on an offset and a limit.

• offset_query_param (default: page[offset])
• limit_query_param (default: page[limit])
• default_limit (default: REST_FRAMEWORK['PAGE_SIZE'])
• max_limit (default: 100)

from rest_framework_json_api.pagination import JsonApiPageNumberPagination, JsonApiLimitOffsetPagination

class MyPagePagination(JsonApiPageNumberPagination):
    page_query_param = 'page_number'
    page_size_query_param = 'page_length'
    page_size = 3
    max_page_size = 1000

class MyLimitPagination(JsonApiLimitOffsetPagination):
    offset_query_param = 'offset'
    limit_query_param = 'limit'
    default_limit = 3
    max_limit = None

Django REST framework (DRF) typically produces a flat response structure. When using django-rest-framework-json-api, the response is transformed to follow the JSON:API specification, which includes links, data (with type, id, and attributes), and meta (for pagination).

// Standard DRF response format
{
    "count": 20,
    "next": "https://example.com/api/1.0/identities/?page=3",
    "previous": "https://example.com/api/1.0/identities/?page=1",
    "results": [{
        "id": 3,
        "username": "john",
        "full_name": "John Coltrane"
    }]
}

// JSON:API compliant response format
{
    "links": {
        "first": "https://example.com/api/1.0/identities",
        "last": "https://example.com/api/1.0/identities?page=5",
        "next": "https://example.com/api/1.0/identities?page=3",
        "prev": "https://example.com/api/1.0/identities",
    },
    "data": [{
        "type": "identities",
        "id": "3",
        "attributes": {
            "username": "john",
            "full-name": "John Coltrane"
        }
    }],
    "meta": {
        "pagination": {
          "page": "2",
          "pages": "5",
          "count": "20"
        }
    }
}

The resource_name property determines the type attribute in JSON:API responses. It is automatically set as the plural of the view or model name, but you can manually override it.

Resolution order: View > Serializer > Model.

• On a View: Set resource_name = 'name' directly on the view class.
• On a Serializer: Set resource_name = 'name' on the serializer class.
• On a Model: Include a JSONAPIMeta class within the model containing the resource_name property.

Note: Setting resource_name on a view can cause the type to change depending on which endpoint is used to fetch the resource.

# Example - resource_name on View
class Me(generics.GenericAPIView):
    resource_name = 'users'
    serializer_class = identity_serializers.IdentitySerializer
    allowed_methods = ['GET']
    permission_classes = (permissions.IsAuthenticated, )

# Example - resource_name on Model
class Me(models.Model):
    name = models.CharField(max_length=100)

class JSONAPIMeta:
    resource_name = "users"

To support JSON:API related URLs (e.g., /orders/3/lineitems/), configure your urls.py to handle a pattern that captures the parent pk and a related_field.

In your serializer, use ResourceRelatedField and map it to the view name using related_link_view_name. Ensure the related_link_url_kwarg matches the name of the parameter in your URL regex (usually 'pk').

Note: Related resources are served by the same view as the parent. Therefore, permission checks are performed on the parent object; if the user can access the parent, they can access the related resource.

# urls.py
url(r'^orders/(?P<pk>[^/.]+)/$', OrderViewSet.as_view({'get': 'retrieve'}), name='order-detail'),
url(r'^orders/(?P<pk>[^/.]+)/(?P<related_field>[-\w]+)/$', OrderViewSet.as_view({'get': 'retrieve_related'}), name='order-related'),

# serializers.py
class OrderSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Order

    related_serializers = {
        'customer': 'example.serializers.CustomerSerializer',
        'line_items': 'example.serializers.LineItemSerializer'
    }

    line_items = ResourceRelatedField(
        queryset=LineItem.objects,
        many=True,
        related_link_view_name='order-related',
        related_link_url_kwarg='pk',
        self_link_view_name='order-relationships'
    )

Polymorphic resources allow a single endpoint to expose different specialized subclasses (e.g., an ArtProject and a ResearchProject under a Project endpoint).

Note: Support for django-polymorphic is deprecated and will be removed in a future release. There is currently no replacement.

To implement polymorphic resources:

1. Install the dependency: pip install djangorestframework-jsonapi['django-polymorphic'].
2. Use serializers.PolymorphicModelSerializer and define the polymorphic_serializers list.
3. For relationships, use relations.PolymorphicResourceRelatedField and pass the base polymorphic serializer as the first argument.

# Polymorphic Serializer
class ProjectSerializer(serializers.PolymorphicModelSerializer):
    polymorphic_serializers = [ArtProjectSerializer, ResearchProjectSerializer]

    class Meta:
        model = models.Project

# Polymorphic Relation
class CompanySerializer(serializers.ModelSerializer):
    current_project = relations.PolymorphicResourceRelatedField(
        ProjectSerializer, 
        queryset=models.Project.objects.all()
    )