Skip to content
It introduces "Problem Details" in the HTTP APIs.
Python
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
drf_problems Fixed issues with existing exceptions. Jun 9, 2019
.gitignore Added README and fixed bugs. Jun 2, 2019
LICENSE Added License May 26, 2019
MANIFEST.in Added License May 26, 2019
README.md Updated README Jun 7, 2019
setup.py Added proper versioning in setup May 26, 2019

README.md

DRF Problems PyPI version

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

  • 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

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.

You can’t perform that action at this time.