Django Ninja Extra

Common errors

• TypeError: Cannot create a consistent method resolution order (MRO) for bases PaginatedResponseSchema, Generic

  cause Incompatible inheritance hierarchy, often due to a specific interaction between django-ninja-extra's PaginatedResponseSchema and certain Pydantic versions.
  fix This specific MRO issue was largely addressed with the Pydantic v2 migration in `django-ninja-extra>=0.30.9`. Ensure you are on the latest compatible versions of `django-ninja-extra` and `pydantic`. If on an older `django-ninja-extra` version, try pinning `pydantic` to `pydantic<2.0,>=1.10.0`.

• HTTP 405 Method Not Allowed

  cause Attempting an HTTP method (e.g., POST) on a controller route that only has a decorator for a different method (e.g., `@http_get`).
  fix Ensure the controller method is decorated with the correct HTTP verb decorator for the request you are making (e.g., `@http_post`, `@http_put`, `@http_delete`).

• AttributeError: 'NinjaExtraAPI' object has no attribute 'register_controller'

  cause Misspelling the method to register controllers or attempting to register a controller with a standard `NinjaAPI` instance.
  fix Ensure you are using `NinjaExtraAPI()` and call `api.register_controllers(YourControllerClass)`. Note the plural `controllers`.

• pydantic.error_wrappers.ValidationError: 1 validation error for YourSchema

  cause Input data for a request body or query parameters does not conform to the Pydantic schema defined for the endpoint.
  fix Review the API endpoint's expected schema and ensure the incoming request data matches the types, required fields, and constraints defined in your Pydantic model. Check for missing required fields or incorrect data types.

• ModuleNotFoundError: No module named 'ninja_extra.controllers'

  cause Attempting to import a symbol from an incorrect or deprecated path within `django-ninja-extra`.
  fix Always refer to the official documentation for current import paths. Many core components are directly available from `ninja_extra` (e.g., `from ninja_extra import api_controller`) rather than deeper submodules like `ninja_extra.controllers`.

Warnings

• breaking Version 0.30.9 introduced a migration from Pydantic v1 config to Pydantic v2 config. This is a significant breaking change if your project relies on Pydantic v1 specific syntax or behaviors.
  Fix: Review the Pydantic v2 migration guide (https://pydantic.dev/latest/migration/) and update your schemas and configuration accordingly. Ensure all Pydantic-related code adheres to v2 standards.
• deprecated The `get_api_controller()` method has been deprecated and replaced by the `api_controller` property for accessing controller instances within the API.
  Fix: Replace calls to `api.get_api_controller(YourController)` with `api.api_controller[YourController]` or access it directly if already registered. For example, `api.api_controller[ItemController].list_items()`.
• breaking In versions prior to 0.22.2, the `service` attribute in `ModelController` was expected to be a class object. It was changed to an instance object, requiring `service_type` to be specified.
  Fix: If defining a custom ModelService for a ModelController, specify it using `service_type = YourCustomModelService` instead of directly assigning to `service`.
• gotcha Prior to versions 0.31.3/0.31.4, there were issues with API-level authentication and throttling not correctly inheriting to controller routes.
  Fix: Upgrade to `django-ninja-extra` version 0.31.3 or higher to ensure proper inheritance of API-level authentication and throttling. Manually apply auth/throttle decorators to individual routes as a workaround for older versions.
• gotcha An MRO (Method Resolution Order) bug might occur with `PaginatedResponseSchema` when using `django-ninja-extra>=0.21` in combination with specific Pydantic versions, causing `TypeError: Cannot create a consistent method resolution order (MRO)`.
  Fix: This issue was largely resolved with the Pydantic v2 migration in 0.30.9. Ensure your `django-ninja-extra` and `pydantic` versions are up-to-date and compatible. If still encountering, try pinning `pydantic` to a compatible v1 version (e.g., `pydantic<2.0,>=1.10`) for older `django-ninja-extra` versions.

Install

• pip install django-ninja-extra Install with pip

Imports

• NinjaExtraAPI
  wrong:

  from ninja import NinjaAPI

  correct:

  from ninja_extra import NinjaExtraAPI

  While NinjaExtraAPI inherits from NinjaAPI, directly importing NinjaAPI will miss extra features.
• api_controller

  from ninja_extra import api_controller

  Decorator for defining class-based API controllers.
• http_get

  from ninja_extra import http_get

  HTTP method decorator for controller methods (e.g., @http_get).
• ModelControllerBase

  from ninja_extra import ModelControllerBase

  Base class for generating CRUD operations for Django models.
• ModelService

  from ninja_extra import ModelService

  Base class for defining custom service logic for ModelControllers.

Quickstart

This quickstart demonstrates how to set up a basic API using `NinjaExtraAPI` and define a class-based `APIController` with two simple GET routes. It includes the necessary Django setup for a runnable example. The controller is registered with the main API instance, and its routes are then exposed via Django's URL configuration. Remember to add 'ninja_extra' to your `INSTALLED_APPS`.

import os
from django.conf import settings
from django.urls import path
from ninja_extra import NinjaExtraAPI, api_controller, http_get

if not settings.configured:
    settings.configure(
        DEBUG=True,
        INSTALLED_APPS=[
            'django.contrib.auth',
            'django.contrib.contenttypes',
            'ninja_extra',
        ],
        ROOT_URLCONF=__name__,
        SECRET_KEY='a-very-secret-key',
        TEMPLATES=[{
            'BACKEND': 'django.template.backends.django.DjangoTemplates',
            'APP_DIRS': True,
        }],
    )

api = NinjaExtraAPI()

@api_controller("/items", tags=["Items"])
class ItemController:
    @http_get("/")
    def list_items(self):
        return [{"id": 1, "name": "Item 1"}, {"id": 2, "name": "Item 2"}]

    @http_get("/{item_id}")
    def get_item(self, item_id: int):
        return {"id": item_id, "name": f"Item {item_id}"}

api.register_controllers(ItemController)

urlpatterns = [
    path("api/", api.urls),
]

# To run this in a Django project, you'd integrate `api.urls` into your project's `urls.py`:
# from django.urls import path, include
# from .api import api # Assuming your api setup is in api.py
# urlpatterns = [
#     path("api/", api.urls),
# ]
# Remember to add 'ninja_extra' to your INSTALLED_APPS in settings.py