The 3.4 release is the first in a planned series that will be addressing schema generation, hypermedia support, API clients, and finally realtime support.
The 3.4 release has been made possible a recent Mozilla grant, and by our collaborative funding model. If you use REST framework commercially, and would like to see this work continue, we strongly encourage you to invest in its continued development by signing up for a paid plan.
The initial aim is to provide a single full-time position on REST framework. Right now we're over 60% of the way towards achieving that. Every single sign-up makes a significant impact.
REST framework 3.4 brings built-in support for generating API schemas.
We provide this support by using Core API, a Document Object Model for describing APIs.
Because Core API represents the API schema in an format-independent
manner, we're able to render the Core API
Document object into many different
schema formats, by allowing the renderer class to determine how the internal
representation maps onto the external schema format.
This approach should also open the door to a range of auto-generated API
documentation options in the future, by rendering the
Document object into
HTML documentation pages.
Alongside the built-in schema support, we're also now providing the following:
These API clients are dynamically driven, and able to interact with any API that exposes a supported schema format.
Dynamically driven clients allow you to interact with an API at an application layer interface, rather than a network layer interface, while still providing the benefits of RESTful Web API design.
We're expecting to expand the range of languages that we provide client libraries for over the coming months.
Further work on maturing the API schema support is also planned, including documentation on supporting file upload and download, and improved support for documentation generation and parameter annotation.
Current support for schema formats is as follows:
|Core JSON||Schema generation & client support.||Built-in support in
|Swagger / OpenAPI||Schema generation & client support.||The
|JSON Hyper-Schema||Currently client support only.||The
|API Blueprint||Not yet available.||Not yet available.|
You can read more about any of this new functionality in the following:
- New tutorial section on schemas & client libraries.
- Documentation page on schema generation.
- Topic page on API clients.
It is also worth noting that Marc Gibbons is currently working towards a 2.0 release of the popular Django REST Swagger package, which will tie in with our new built-in support.
The 3.4.0 release adds support for Django 1.10.
The following versions of Python and Django are now supported:
- Django versions 1.8, 1.9, and 1.10.
- Python versions 2.7, 3.2(*), 3.3(*), 3.4, 3.5.
(*) Note that Python 3.2 and 3.3 are not supported from Django 1.9 onwards.
The 3.4 release includes very limited deprecation or behavioral changes, and should present a straightforward upgrade.
The following change in 3.3.0 is now escalated from "pending deprecation" to "deprecated". Its usage will continue to function but will raise warnings:
HyperlinkedModelSerializer should include either a
option, or an
exclude option. The
fields = '__all__' shortcut may be used
to explicitly include all fields.
Using the default JSON renderer and directly returning a
instance will now render with microsecond precision (6 digits), rather than
millisecond precision (3 digits). This makes the output format consistent with the
default string output of
This change does not affect the default behavior when using serializers,
which is to serialize
time instances into strings with
The serializer behavior can be modified if needed, using the
The renderer behavior can be modified by setting a custom
attribute on a
OPTIONS request to views that have a serializer choice field
will result in a list of the available choices being returned in the response.
In cases where there is a relational field, the previous behavior would be to return a list of available instances to choose from for that relational field.
In order to minimise exposed information the behavior now is to not return choices information for relational fields.
If you want to override this new behavior you'll need to implement a custom metadata class.
See issue #3751 for more information on this behavioral change.
This release includes further work from a huge number of pull requests and issues.
Many thanks to all our contributors who've been involved in the release, either through raising issues, giving feedback, improving the documentation, or suggesting and implementing code changes.
The full set of itemized release notes are available here.