Third Party Packages
Software ecosystems […] establish a community that further accelerates the sharing of knowledge, content, issues, expertise and skills.
— Jan Bosch.
About Third Party Packages
Third Party Packages allow developers to share code that extends the functionality of Django REST framework, in order to support additional use-cases.
We support, encourage and strongly favor the creation of Third Party Packages to encapsulate new behavior rather than adding additional functionality directly to Django REST Framework.
We aim to make creating third party packages as easy as possible, whilst keeping a simple and well maintained core API. By promoting third party packages we ensure that the responsibility for a package remains with its author. If a package proves suitably popular it can always be considered for inclusion into the core REST framework.
If you have an idea for a new feature please consider how it may be packaged as a Third Party Package. We're always happy to discuss ideas on the Mailing List.
How to create a Third Party Package
Creating your package
You can use this cookiecutter template for creating reusable Django REST Framework packages quickly. Cookiecutter creates projects from project templates. While optional, this cookiecutter template includes best practices from Django REST framework and other packages, as well as a Travis CI configuration, Tox configuration, and a sane setup.py for easy PyPI registration/distribution.
Note: Let us know if you have an alternate cookiecuter package so we can also link to it.
Running the initial cookiecutter command
To run the initial cookiecutter command, you'll first need to install the Python cookiecutter
package.
$ pip install cookiecutter
Once cookiecutter
is installed just run the following to create a new project.
$ cookiecutter gh:jpadilla/cookiecutter-django-rest-framework
You'll be prompted for some questions, answer them, then it'll create your Python package in the current working directory based on those values.
full_name (default is "Your full name here")? Johnny Appleseed
email (default is "you@example.com")? jappleseed@example.com
github_username (default is "yourname")? jappleseed
pypi_project_name (default is "dj-package")? djangorestframework-custom-auth
repo_name (default is "dj-package")? django-rest-framework-custom-auth
app_name (default is "djpackage")? custom_auth
project_short_description (default is "Your project description goes here")?
year (default is "2014")?
version (default is "0.1.0")?
Getting it onto GitHub
To put your project up on GitHub, you'll need a repository for it to live in. You can create a new repository here. If you need help, check out the Create A Repo article on GitHub.
Adding to Travis CI
We recommend using Travis CI, a hosted continuous integration service which integrates well with GitHub and is free for public repositories.
To get started with Travis CI, sign in with your GitHub account. Once you're signed in, go to your profile page and enable the service hook for the repository you want.
If you use the cookiecutter template, your project will already contain a .travis.yml
file which Travis CI will use to build your project and run tests. By default, builds are triggered everytime you push to your repository or create Pull Request.
Uploading to PyPI
Once you've got at least a prototype working and tests running, you should publish it on PyPI to allow others to install it via pip
.
You must register an account before publishing to PyPI.
To register your package on PyPI run the following command.
$ python setup.py register
If this is the first time publishing to PyPI, you'll be prompted to login.
Note: Before publishing you'll need to make sure you have the latest pip that supports wheel
as well as install the wheel
package.
$ pip install --upgrade pip
$ pip install wheel
After this, every time you want to release a new version on PyPI just run the following command.
$ python setup.py publish
You probably want to also tag the version now:
git tag -a {0} -m 'version 0.1.0'
git push --tags
After releasing a new version to PyPI, it's always a good idea to tag the version and make available as a GitHub Release.
We recommend to follow Semantic Versioning for your package's versions.
Development
Version requirements
The cookiecutter template assumes a set of supported versions will be provided for Python and Django. Make sure you correctly update your requirements, docs, tox.ini
, .travis.yml
, and setup.py
to match the set of versions you wish to support.
Tests
The cookiecutter template includes a runtests.py
which uses the pytest
package as a test runner.
Before running, you'll need to install a couple test requirements.
$ pip install -r requirements.txt
Once requirements installed, you can run runtests.py
.
$ ./runtests.py
Run using a more concise output style.
$ ./runtests.py -q
Run the tests using a more concise output style, no coverage, no flake8.
$ ./runtests.py --fast
Don't run the flake8 code linting.
$ ./runtests.py --nolint
Only run the flake8 code linting, don't run the tests.
$ ./runtests.py --lintonly
Run the tests for a given test case.
$ ./runtests.py MyTestCase
Run the tests for a given test method.
$ ./runtests.py MyTestCase.test_this_method
Shorter form to run the tests for a given test method.
$ ./runtests.py test_this_method
To run your tests against multiple versions of Python as different versions of requirements such as Django we recommend using tox
. Tox is a generic virtualenv management and test command line tool.
First, install tox
globally.
$ pip install tox
To run tox
, just simply run:
$ tox
To run a particular tox
environment:
$ tox -e envlist
envlist
is a comma-separated value to that specifies the environments to run tests against. To view a list of all possible test environments, run:
$ tox -l
Version compatibility
Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries, you'll need to run slightly different code depending on the environment. Any code that branches in this way should be isolated into a compat.py
module, and should provide a single common interface that the rest of the codebase can use.
Check out Django REST framework's compat.py for an example.
Once your package is available
Once your package is decently documented and available on PyPI, you might want share it with others that might find it useful.
Adding to the Django REST framework grid
We suggest adding your package to the REST Framework grid on Django Packages.
Adding to the Django REST framework docs
Create a Pull Request or Issue on GitHub, and we'll add a link to it from the main REST framework documentation. You can add your package under Third party packages of the API Guide section that best applies, like Authentication or Permissions. You can also link your package under the Third Party Packages section.
Announce on the discussion group.
You can also let others know about your package through the discussion group.
Existing Third Party Packages
Django REST Framework has a growing community of developers, packages, and resources.
Check out a grid detailing all the packages and ecosystem around Django REST Framework at Django Packages.
To submit new content, open an issue or create a pull request.
Authentication
- djangorestframework-digestauth - Provides Digest Access Authentication support.
- django-oauth-toolkit - Provides OAuth 2.0 support.
- doac - Provides OAuth 2.0 support.
- djangorestframework-jwt - Provides JSON Web Token Authentication support.
- djangorestframework-simplejwt - An alternative package that provides JSON Web Token Authentication support.
- hawkrest - Provides Hawk HTTP Authorization.
- djangorestframework-httpsignature - Provides an easy to use HTTP Signature Authentication mechanism.
- djoser - Provides a set of views to handle basic actions such as registration, login, logout, password reset and account activation.
- django-rest-auth - Provides a set of REST API endpoints for registration, authentication (including social media authentication), password reset, retrieve and update user details, etc.
- drf-oidc-auth - Implements OpenID Connect token authentication for DRF.
- drfpasswordless - Adds (Medium, Square Cash inspired) passwordless logins and signups via email and mobile numbers.
Permissions
- drf-any-permissions - Provides alternative permission handling.
- djangorestframework-composed-permissions - Provides a simple way to define complex permissions.
- rest_condition - Another extension for building complex permissions in a simple and convenient way.
- dry-rest-permissions - Provides a simple way to define permissions for individual api actions.
Serializers
- django-rest-framework-mongoengine - Serializer class that supports using MongoDB as the storage layer for Django REST framework.
- djangorestframework-gis - Geographic add-ons
- djangorestframework-hstore - Serializer class to support django-hstore DictionaryField model field and its schema-mode feature.
- djangorestframework-jsonapi - Provides a parser, renderer, serializers, and other tools to help build an API that is compliant with the jsonapi.org spec.
- html-json-forms - Provides an algorithm and serializer to process HTML JSON Form submissions per the (inactive) spec.
- django-rest-framework-serializer-extensions - Enables black/whitelisting fields, and conditionally expanding child serializers on a per-view/request basis.
- djangorestframework-queryfields - Serializer mixin allowing clients to control which fields will be sent in the API response.
Serializer fields
- drf-compound-fields - Provides "compound" serializer fields, such as lists of simple values.
- django-extra-fields - Provides extra serializer fields.
- django-versatileimagefield - Provides a drop-in replacement for Django's stock
ImageField
that makes it easy to serve images in multiple sizes/renditions from a single field. For DRF-specific implementation docs, click here.
Views
- djangorestframework-bulk - Implements generic view mixins as well as some common concrete generic views to allow to apply bulk operations via API requests.
- django-rest-multiple-models - Provides a generic view (and mixin) for sending multiple serialized models and/or querysets via a single API request.
Routers
- drf-nested-routers - Provides routers and relationship fields for working with nested resources.
- wq.db.rest - Provides an admin-style model registration API with reasonable default URLs and viewsets.
Parsers
- djangorestframework-msgpack - Provides MessagePack renderer and parser support.
- djangorestframework-jsonapi - Provides a parser, renderer, serializers, and other tools to help build an API that is compliant with the jsonapi.org spec.
- djangorestframework-camel-case - Provides camel case JSON renderers and parsers.
Renderers
- djangorestframework-csv - Provides CSV renderer support.
- djangorestframework-jsonapi - Provides a parser, renderer, serializers, and other tools to help build an API that is compliant with the jsonapi.org spec.
- drf_ujson - Implements JSON rendering using the UJSON package.
- rest-pandas - Pandas DataFrame-powered renderers including Excel, CSV, and SVG formats.
- djangorestframework-rapidjson - Provides rapidjson support with parser and renderer.
Filtering
- djangorestframework-chain - Allows arbitrary chaining of both relations and lookup filters.
- django-url-filter - Allows a safe way to filter data via human-friendly URLs. It is a generic library which is not tied to DRF but it provides easy integration with DRF.
- drf-url-filter is a simple Django app to apply filters on drf
ModelViewSet
'sQueryset
in a clean, simple and configurable way. It also supports validations on incoming query params and their values.
Misc
- cookiecutter-django-rest - A cookiecutter template that takes care of the setup and configuration so you can focus on making your REST apis awesome.
- djangorestrelationalhyperlink - A hyperlinked serialiser that can can be used to alter relationships via hyperlinks, but otherwise like a hyperlink model serializer.
- django-rest-swagger - An API documentation generator for Swagger UI.
- django-rest-framework-proxy - Proxy to redirect incoming request to another API server.
- gaiarestframework - Utils for django-rest-framework
- drf-extensions - A collection of custom extensions
- ember-django-adapter - An adapter for working with Ember.js
- django-versatileimagefield - Provides a drop-in replacement for Django's stock
ImageField
that makes it easy to serve images in multiple sizes/renditions from a single field. For DRF-specific implementation docs, click here. - drf-tracking - Utilities to track requests to DRF API views.
- drf_tweaks - Serializers with one-step validation (and more), pagination without counts and other tweaks.
- django-rest-framework-braces - Collection of utilities for working with Django Rest Framework. The most notable ones are FormSerializer and SerializerForm, which are adapters between DRF serializers and Django forms.
- drf-haystack - Haystack search for Django Rest Framework
- django-rest-framework-version-transforms - Enables the use of delta transformations for versioning of DRF resource representations.
- django-rest-messaging, django-rest-messaging-centrifugo and django-rest-messaging-js - A real-time pluggable messaging service using DRM.
- djangorest-alchemy - SQLAlchemy support for REST framework.