Never liked DRF plain old errors? Forget that and accept RFC 7807 - Problem Details!
Project description
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.
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
Contributing
Contributions are very welcome, of any kind - whether finding new issues or any ideas for enhancements or a pull request.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for drf_problems-1.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d56468e36f77b777596cbced532185869a5b2fa8d9519d5b6ef72ed6682d5033 |
|
MD5 | db3690d84ffde9efe2ef66eeb9d9f13f |
|
BLAKE2b-256 | ecd8dd1ba9143ef51ca19424229728d06b27d7aa33d4483b3e2912f518f832a8 |