041b88f8bb
* Improve style, fix some typos * Update docs/api-guide/fields.md Co-authored-by: Tom Christie <tom@tomchristie.com> Co-authored-by: Tom Christie <tom@tomchristie.com>
7.9 KiB
Django REST framework 3.4
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.
Funding
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.
Many thanks to all our awesome sponsors, and in particular to our premium backers, Rover, Sentry, and Stream.
Schemas & client libraries
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:
- A command line tool for interacting with APIs.
- A Python client library for interacting with APIs.
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:
| Name | Support | PyPI package |
|---|---|---|
| Core JSON | Schema generation & client support. | Built-in support in coreapi. |
| Swagger / OpenAPI | Schema generation & client support. | The openapi-codec package. |
| JSON Hyper-Schema | Currently client support only. | The hyperschema-codec package. |
| 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.
Supported versions
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.
Deprecations and changes
The 3.4 release includes very limited deprecation or behavioral changes, and should present a straightforward upgrade.
Use fields or exclude on serializer classes.
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 and HyperlinkedModelSerializer should include either a fields
option, or an exclude option. The fields = '__all__' shortcut may be used
to explicitly include all fields.
Microsecond precision when returning time or datetime.
Using the default JSON renderer and directly returning a datetime or time
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 serializers.DateTimeField and serializers.TimeField.
This change does not affect the default behavior when using serializers,
which is to serialize datetime and time instances into strings with
microsecond precision.
The serializer behavior can be modified if needed, using the DATETIME_FORMAT
and TIME_FORMAT settings.
The renderer behavior can be modified by setting a custom encoder_class
attribute on a JSONRenderer subclass.
Relational choices no longer displayed in OPTIONS requests.
Making an 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.
Other improvements
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.