Django REST Framework - JSON API

A parser and renderer for Django REST Framework that adds support for the JSON API specification.

Build status: Build Status

Does this work?

This package is currently being actively developed, but is not widely used in production. If you find any problems when using this package, please create a bug report at the issue tracker so we can figure out how to fix it.

How do I use this?

This is designed to be used as only a renderer and parser and does not provide any additional functionality that may be expected by JSON API.

Specific to a view(set)

from rest_framework import generics
from rest_framework_json_api.renderers import JsonApiRenderer


class ExampleView(generics.ListAPIView):
    renderer_classes = (JsonApiRenderer, )

The JSON API renderer is not limited to just list views and can be used on any of the generic views. It supports viewsets as well as non-generic views.

All views

The JSON API renderer can be used on all views by setting it as a default renderer.

# ...
REST_FRAMEWORK = {
    "DEFAULT_RENDERER_CLASSES": (
        "rest_framework_json_api.renderers.JsonApiRenderer",
        "rest_framework.renderers.BrowsableAPIRenderer",
        # Any other renderers
    ),
    "DEFAULT_PARSER_CLASSES": (
        "rest_framework_json_api.parsers.JsonApiParser",
        "rest_framework.parsers.FormParser",
        "rest_framework.parsers.MultiPartParser",
        # Any other parsers
    ),
}
#...

This may break the API root view of the Default Router, so you may want to instead apply it to your viewsets.

What does this support?

The JSON API renderer supports all features of hyperlinked serializers and will normalize attributes such as the url field to match the JSON API specification.

Introspected resource types

JSON API uses resource types to determine what relations exist and how to better side-load resources automatically. It is recommended that resource types match the URL structure of the API and use a plural form. The resource type is determined from the model, and is the plural form of the verbose model name.

If a verbose name cannot be determined, the generic keydata will be used for the resource type.

Hyperlinked relations

JSON API will detect hyperlinked relations and set up the url templates to match the destinations and attribute names automatically.

Nested serializers

JSON API will render nested serializers to match the compound document specification. This will theoretically support any depth of nested serializers, but only a single level is tested and supported.

What this will not easily support

Due to limitations within the JSON API specification, as well as a need to handle the most common easy cases, this JSON API renderer will not work with all views. When designing views that work well with the JSON API specification, there are a few needs that you should keep in mind.

Isn’t JSON API being actively developed?

Yes it is, and we will try to keep this package as close to the running specification as possible. This means that things may break during version changes, and until JSON API becomes stable we cannot guarantee backwards compatibility. Once JSON API stabilizes, a deprecation process will be established to match the policies of the JSON API specification.

Feedback

If you have any suggestions or questions about Django REST Framework - JSON API feel free to email me at kevin@kevinbrown.in.

If you encounter any errors or problems with Django REST Framework - JSON API, please let me know! Open an Issue at the GitHub https://github.com/kevin-brown/drf-json-api main repository.