References:

https://stackoverflow.com/questions/503093/how-do-i-redirect-to-another-webpage#506004

Hello world

from ninja import Router
v1_router = Router(tags=["cclib"])


@v1_router.get("/hello")
def hello(request):
    return "Hello world!"

A basic example to expose a Django Model

from typing import List
import uuid
from django.shortcuts import get_object_or_404
from ninja import Router
from ninja import Schema, ModelSchema
from ninja.security import django_auth

from cclib.resources.models import Document

v1_router = Router(tags=["cclib"])


class DocumentSchema(ModelSchema):
    class Meta:
        model = Document
        fields = "__all__"


@v1_router.get("/documents/{uuid:document_id}", response=DocumentSchema, auth=django_auth)
def get_document(request, document_id: uuid.UUID):
    return get_object_or_404(Document, pk=document_id)


@v1_router.get("/documents", response=List[DocumentSchema], auth=django_auth)
def list_documents(request):
    qs = Document.objects.all()
    return qs

Nested objects

There is also often a need to return responses with some nested/child objects ...

https://django-ninja.dev/guides/response/#nested-objects

See also:

Django Ninja nested Schemas

Example:

import traceback
from typing import List
from ninja import Router
from ninja import Schema, ModelSchema
from ninja.errors import HttpError
from ninja.security import django_auth
from ninja.security import django_auth_superuser
from django.conf import settings
from django.contrib.auth.models import Group
from django.contrib.auth import get_user_model

v1_router = Router(tags=["ccserver"])


class GroupSchema(ModelSchema):
    class Meta:
        model = Group
        fields = "__all__"

class UserSchema(ModelSchema):
    # See: "Nested objects"
    # https://django-ninja.dev/guides/response/#nested-objects
    groups: List[GroupSchema] = []
    class Meta:
        model = get_user_model()
        #fields = "__all__"
        fields = [
            'id',
            'username',
        ]


@v1_router.get("/users", response=List[UserSchema], auth=django_auth_superuser)
def list_users(request):
    try:
        User = get_user_model()
        qs = User.objects.all()
    except Exception as e:
        # See: "Throwing HTTP responses with exceptions"
        # https://django-ninja.dev/guides/errors/#throwing-http-responses-with-exceptions
        raise HttpError(500, str(e) + "\n" + traceback.format_exc())

    return qs

Filtering

https://django-ninja.dev/guides/input/filtering/

Aliases

Instead of a nested response, you may want to just flatten the response output.

The Ninja Schema object extends Pydantic's Field(..., alias="") format to work with dotted responses.

See: https://django-ninja.dev/guides/response/#aliases

Authentication

https://django-ninja.dev/guides/authentication/

Examples:

from ninja import NinjaAPI
from ninja.security import django_auth

api = NinjaAPI(csrf=True)

@api.get("/pets", auth=django_auth)
def pets(request):
    return f"Authenticated user {request.auth}"

If you need to authorize only a superuser, you can use from ninja.security import django_auth_superuser instead.

Here's an example where the client, in order to authenticate, needs to pass a header:

Authorization: Bearer supersecret:

from ninja.security import HttpBearer


class AuthBearer(HttpBearer):
    def authenticate(self, request, token):
        if token == "supersecret":
            return token


@api.get("/bearer", auth=AuthBearer())
def bearer(request):
    return {"token": request.auth}

Throwing HTTP responses with exceptions

As an alternative to custom exceptions and writing handlers for it - you can as well throw http exception that will lead to returning a http response with desired code

https://django-ninja.dev/guides/errors/#throwing-http-responses-with-exceptions

from ninja.errors import HttpError

@api.get("/some/resource")
def some_operation(request):
    if True:
        raise HttpError(503, "Service Unavailable. Please retry later.")

Best practices

Have separate routers for each domain:

https://django-ninja.dev/guides/routers/

See also the following discussion:

https://www.reddit.com/r/django/comments/13zg8uw/django_ninja_architecture/

Fetching JSON with JavaScript Fetch API

Quick and easy:

 fetch('https://reqbin.com/echo/get/json', {
     method: 'GET',
     headers: {
         'Accept': 'application/json',
     },
 })
.then(response => response.json())
.then(response => console.log(JSON.stringify(response)))

Example 1

The following is more elaborated with the purpose to collect all errors is a single catch handler:

• either if a network error occurs,
• or if the response is not 200-OK

In the latter case, the response might contain further details JSON-serialized and we want to inspect them

fetch(
    '/backend/j/mto_evaluate_final_stock_total', {
        method: "post",
        body: data,
        mode: 'cors',   // 'no-cors',
        cache: 'no-cache',
        credentials: 'same-origin',
        headers: {
            // make sure request.is_ajax() return True on the server
            'X-Requested-With': 'XMLHttpRequest',
            'X-CSRFToken': getCookie('csrftoken')
        }
    }
)
.then(function(response) {
    if (response.ok) {
        return response.json()
    }
    // if not 200-OK, reject instead of throw
    // Here, the plan is to get {status: 4XX, message: 'a message'} format as a result in both cases.
    // See: https://stackoverflow.com/questions/38235715/fetch-reject-promise-and-catch-the-error-if-status-is-not-ok#67660773
    return Promise.reject(response)
})
.then(function(data) {
    console.log(data)
    ... use data ...
})
.catch(function(error) {
    // Show error
    console.error(error.status, error.statusText);
    // also get error messages, if any
    // Again, see: https://stackoverflow.com/questions/38235715/fetch-reject-promise-and-catch-the-error-if-status-is-not-ok#67660773
    error.json().then(function(json) {
        console.error(json);
    })
})
.finally(function() {
})

Example 2

// bind to the form’s submit event
form.addEventListener('submit', function(event) {

    // prevent the form from performing its default submit action
    event.preventDefault();
    header.classList.add('loading');

    // serialize the form’s content and send via an AJAX call
    // using the form’s defined method and action
    let url = form.getAttribute('action') || self.options.url;
    let method = form.getAttribute('method') || 'post';
    // We use FormData // to allow files upload (i.e. process <input type="file"> as expected)
    // Note that, using FormData, we also need (with jQuery):
    // - processData: false
    // - contentType: false
    let data = new FormData(form);
    //console.log('form data: %o', new URLSearchParams(data).toString());

    self._notify('submitting', {method: method, url: url, data:data});

    let promise = fetch(
        self.options.url, {
            method: "post",
            body: data,
            mode: 'cors',   // 'no-cors',
            cache: 'no-cache',
            credentials: 'same-origin',
            headers: {
                // make sure request.is_ajax() return True on the server
                'X-Requested-With': 'XMLHttpRequest',
                'X-CSRFToken': getCookie('csrftoken')
            }
        }
    );
    promise.then(response => {
        if (response.ok) {
            // Upon receiving a JSON response, we assume that the form has been validated,
            // so we can close the modal
            if (response.headers.get('Content-Type') === 'application/json') {
                response.json().then(data => {
                    self._notify('submitted', {method: method, url: url, data: data});
                    self.close();
                })
                .catch(error => {
                    FrontendForms.display_server_error(error);
                })
            }
            else {
                response.text().then(data => {

                    // update the modal body with the new form
                    body.innerHTML = data;

                    // Does the response contain a form ?
                    let form = self.element.querySelector('.dialog-content .dialog-body form');
                    if (form !== null) {
                        // If the server sends back a successful response,
                        // we need to further check the HTML received

                        // If xhr contains any field errors,
                        // the form did not validate successfully,
                        // so we keep it open for further editing
                        //if (jQuery(xhr).find('.has-error').length > 0) {

                        if (form.querySelectorAll('.has-error').length > 0 || form.querySelectorAll('.errorlist').length > 0) {
                            self._notify('loaded', {url: url});
                            self._form_ajax_submit(true);
                        } else {
                            // otherwise, we've done and can close the modal
                            self._notify('submitted', {method: method, url: url, data: data});
                            self.close();
                        }
                    }
                    // If not, assume we received a feedback for the user after successfull submission, so:
                    // - keep the dialog open
                    // - hide the save button
                    else {
                        // We also notify the user about successful submission
                        self._notify('submitted', {method: method, url: url, data: data});
                        btn_save.style.display = 'none';
                    }
                });
            }

        } else {
            self._notify('submission_failure', {method: method, url: url, data: data, error: response.statusText});
            FrontendForms.display_server_error(response.statusText);
        }

    }).catch(error => {
        self._notify('submission_failure', {method: method, url: url, data: data, error:error});
        FrontendForms.display_server_error(error.toString());
    }).finally(() => {
        header.classList.remove('loading');
    });

where:

 function getCookie(name) {
    var value = '; ' + document.cookie,
        parts = value.split('; ' + name + '=');
    if (parts.length == 2) return parts.pop().split(';').shift();
}

Exercise: Return a value after a delay

Strategy:

• the Promise is an object whose constructor accepts an executor function as its only parameter
• that is, a function which receives two parameters resolve and reject which must be two functions (callback)
• in the body of the executor function an asynchronous process is normally invoked by specifying a further "local" callback which will receive the result in due time
• the callback in turn returns the result via resolve
• the only way for the caller to receive the result is to associate a then() method with the Promise

function print(text) {
    element.textContent = text
}

function returnValueAfterDelay(value, delay) {
    let promise = new Promise(function(resolve, reject) {
        function callback() {
            resolve(value)
        }
        setTimeout(callback, delay);
    })
    return promise
}

function main() {
    returnValueAfterDelay(123, 1000).then(
        function(value) {
            print(value)
        }
    )
}

main()

or the similar version using "arrow functions" instead of "regular functions" ... (but does anyone really think it is more readable?) ...

print = (text) => {
    element.textContent = text
}

let returnValueAfterDelay = (value, delay) => {
    let promise = new Promise((resolve, reject) => {
        let callback = () => resolve(value)
        setTimeout(callback, delay)
    })
    return promise
}

let main = () => {
    returnValueAfterDelay(123, 1000).then(
        (value) => print(value)
    )
}

main()

However:

It is recommended to use regular functions when dealing with Promises, Callback functions with dynamic context, and Object methods.