Configuration¶

QueryStringManager reads settings from Django NINJA_JSONAPI.

Settings¶

NINJA_JSONAPI = {
    "DEFAULT_PAGE_SIZE": 20,
    "MAX_PAGE_SIZE": 100,
    "MAX_INCLUDE_DEPTH": 3,
    "ALLOW_DISABLE_PAGINATION": False,
    "INCLUDE_JSONAPI_OBJECT": False,
    "JSONAPI_VERSION": "1.0",
}

Keys¶

• DEFAULT_PAGE_SIZE: default number of items per page when the client doesn't send page[size]. Used by both ApplicationBuilder views and the standalone jsonapi_paginate() helper.
• MAX_PAGE_SIZE: hard upper limit for page[size]. Client-requested sizes above this value are clamped silently.
• MAX_INCLUDE_DEPTH: maximum include chain depth (for example a.b.c).
• ALLOW_DISABLE_PAGINATION: allows/disallows page[size]=0.
  • When True, page[size]=0 disables pagination.
  • When False, page[size]=0 falls back to the default page size.
• INCLUDE_JSONAPI_OBJECT: when True, adds top-level jsonapi object to responses. Applies to both ApplicationBuilder and standalone @jsonapi_resource endpoints.
• JSONAPI_VERSION: version string used when INCLUDE_JSONAPI_OBJECT=True.
• INFLECTION: attribute-key transformation applied to JSON:API documents.
  • None (default) — keys match Python field names.
  • "dasherize" — first_name → first-name.
  • "camelize" — first_name → firstName.
  • See Inflection for details.

Practical guidance¶

• Keep MAX_INCLUDE_DEPTH conservative to avoid expensive graph traversal.
• Set MAX_PAGE_SIZE based on endpoint cost and typical client use.
• Use per-resource operation limits when read-heavy resources need stricter controls.

Query parameters supported¶

• filter
• filter[field]=value
• sort
• include
• fields[resource_type]
• page[number], page[size], page[offset], page[limit]
• page[cursor] (cursor pagination)

Query parameter validation¶

• Unknown query parameters are rejected with 400 Bad Request.
• Repeated parameters are rejected for non-filter keys (for example repeating sort or page[size]).
• Repeating filter[...] keys is allowed.

Include-query optimization¶

The Django ORM data layer now optimizes include paths automatically:

• to-one include chains use select_related
• to-many include chains use prefetch_related

You can also provide explicit include optimization maps on your view:

from django_ninja_jsonapi import ViewBaseGeneric


class CustomerView(ViewBaseGeneric):
    select_for_includes = {
        "__all__": ["company"],
        "owner": ["owner__profile"],
    }
    prefetch_for_includes = {
        "owner": ["owner__groups"],
    }
    django_filterset_class = CustomerFilterSet

Resource meta fields¶

To move selected schema fields into resource meta, define meta_fields:

class CustomerSchema(BaseModel):
    id: int
    name: str
    status: str

    class JSONAPIMeta:
        meta_fields = ["status"]