drf-problems

DRF Problems

TL;DR

This library implements RFC 7807 in our favorite Django REST Framework! Or, in layman terms, it introduces "Problem Details" in the HTTP APIs.

Table of Contents

• Features
• Pre-Requisites
• Installation
• Usage
  • With exceptions
  • With permissions
  • With Views
• Resources
• Roadmap
• Contributing

Features

• Handles exception to return response with Problem Details model.
• Added permission mixins and base class to store exception to raise by the view on failure of permission.
• Added view mixin which throws exception of failed permission.
• These permissions are compatible with composable permissions introduced in DRF 3.9.0!
• Has problem description endpoint to understand about the problem with the given code.
• Has sample permissions which checks for minimum API version.

Pre-Requisites

• Django >= 2.0 (Tested with 2.2)
• djangorestframework >= 3.0.0 (Tested with 3.9.0)

Installation

Install the library as you would for any django library.

• Install using pip. pip install drf-problems
• Add 'drf_problems' to your INSTALLED_APPS setting.

INSTALLED_APPS = (
    ...
    'drf_problems',
)

• DRF's default exception handler needs to be replaced. In your settings.py, update:

REST_FRAMEWORK = {
    ...
    'EXCEPTION_HANDLER': 'drf_problems.exceptions.exception_handler',

• To use the problem description url, you need to update your urls.py:

urlpatterns = [
    ...
    path('', include('drf_problems.urls'))
]

Usage

With exceptions

In your exception class, define default_code with the error code string which is used in the type URI. To set custom title, define title with the human-readable summary of the problem type. To set description, define description with a long paragraph describing the problem.

Finally, make sure to register your exception with drf_problems.utils.register_exception function or drf_problems.utils.register decorator. Here's a sample exception class:

from drf_problems.utils import register_exception, register

@register # Either use this decorator
class InvalidVersionRequestedException(exceptions.NotAcceptable):
    default_code = 'invalid_version'
    title = 'Invalid API version'
    default_detail = 'Provided API version is invalid.')
    description = 'Malformed or unsupported version string is provided with the request.'

register_exception(InvalidVersionRequestedException) # Or this method directly.

With permissions

Use either drf_problems.permissions.ProblemPermissionMixin mixin class with your existing permissions, or extend directly from drf_problems.permissions.BaseProblemPermission. Define exception_class in the permissions to the desired exception class. For flexibility, you can even set exception instance by setting exception attribute on the permission object.

Here's a sample permissions class:

from drf_problems.permissions import BaseProblemPermission

class MinimumVersionRequiredPermission(BaseProblemPermission):
    exception_class = InvalidVersionRequestedException

With Views

Note: The permissions wouldn't throw the desired exception from the view, until the view is extended from the drf_problems.mixins.AllowPermissionWithExceptionViewMixin mixin. So, remember to update your views too, for which permissions are updated!

Resources

• Official Guide
• Problem Details for HTTP APIs
• REST API Error Handling - Problem Details Response

Roadmap

• Add tests with some sample views using exceptions and permissions.
• Document the code better.

Contributing

Contributions are very welcome, of any kind - whether finding new issues or any ideas for enhancements or a pull request.