The 3.4 release is the first in a planned series that will be addressing schemageneration, hypermedia support, API clients, and finally realtime support.
The 3.4 release has been made possible a recentMozilla grant, and by ourcollaborative funding model. If you use REST framework commercially, and wouldlike to see this work continue, we strongly encourage you to invest in itscontinued development bysigning 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.
Many thanks to all ourawesome sponsors, and in particular to our premium backers,Rover,Sentry, andStream.
REST framework 3.4 brings built-in support for generating API schemas.
We provide this support by usingCore API, a Document Object Modelfor describing APIs.
Because Core API represents the API schema in an format-independentmanner, we're able to render the Core APIDocument object into many differentschema formats, by allowing the renderer class to determine how the internalrepresentation maps onto the external schema format.
This approach should also open the door to a range of auto-generated APIdocumentation options in the future, by rendering theDocument object intoHTML 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 APIthat exposes a supported schema format.
Dynamically driven clients allow you to interact with an API at an applicationlayer interface, rather than a network layer interface, while still providingthe benefits of RESTful Web API design.
We're expecting to expand the range of languages that we provide client librariesfor over the coming months.
Further work on maturing the API schema support is also planned, includingdocumentation on supporting file upload and download, and improved support fordocumentation generation and parameter annotation.
Current support for schema formats is as follows:
| Name | Support | PyPI package |
|---|---|---|
| Core JSON | Schema generation & client support. | Built-in support incoreapi. |
| Swagger / OpenAPI | Schema generation & client support. | Theopenapi-codec package. |
| JSON Hyper-Schema | Currently client support only. | Thehyperschema-codec package. |
| API Blueprint | Not yet available. | Not yet available. |
You can read more about any of this new functionality in the following:
It is also worth noting that Marc Gibbons is currently working towards a 2.0 release ofthe 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:
(*) 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, andshould 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:
ModelSerializer andHyperlinkedModelSerializer should include either afieldsoption, or anexclude option. Thefields = '__all__' shortcut may be usedto explicitly include all fields.
Using the default JSON renderer and directly returning adatetime ortimeinstance will now render with microsecond precision (6 digits), rather thanmillisecond precision (3 digits). This makes the output format consistent with thedefault string output ofserializers.DateTimeField andserializers.TimeField.
This changedoes not affect the default behavior when using serializers,which is to serializedatetime andtime instances into strings withmicrosecond precision.
The serializer behavior can be modified if needed, using theDATETIME_FORMATandTIME_FORMAT settings.
The renderer behavior can be modified by setting a customencoder_classattribute on aJSONRenderer subclass.
Making anOPTIONS request to views that have a serializer choice fieldwill 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 beto return a list of available instances to choose from for that relational field.
In order to minimize exposed information the behavior now is tonot returnchoices information for relational fields.
If you want to override this new behavior you'll need toimplement a custommetadata class.
Seeissue #3751 for more information on this behavioral change.
This release includes further work from a huge number ofpull 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 notesare available here.