Release Notes

Release Early, Release Often

— Eric S. Raymond, The Cathedral and the Bazaar.

Versioning

Minor version numbers (0.0.x) are used for changes that are API compatible. You should be able to upgrade between minor point releases without any other code changes.

Medium version numbers (0.x.0) may include API changes, in line with the deprecation policy. You should read the release notes carefully before upgrading between medium point releases.

Major version numbers (x.0.0) are reserved for substantial project milestones.

Deprecation policy

REST framework releases follow a formal deprecation policy, which is in line with Django's deprecation policy.

The timeline for deprecation of a feature present in version 1.0 would work as follows:

Version 1.1 would remain fully backwards compatible with 1.0, but would raise PendingDeprecationWarning warnings if you use the feature that are due to be deprecated. These warnings are silent by default, but can be explicitly enabled when you're ready to start migrating any required changes. For example if you start running your tests using python -Wd manage.py test, you'll be warned of any API changes you need to make.
Version 1.2 would escalate these warnings to DeprecationWarning, which is loud by default.
Version 1.3 would remove the deprecated bits of API entirely.

Note that in line with Django's policy, any parts of the framework not mentioned in the documentation should generally be considered private API, and may be subject to change.

Upgrading

To upgrade Django REST framework to the latest version, use pip:

pip install -U djangorestframework

You can determine your currently installed version using pip freeze:

pip freeze | grep djangorestframework

3.3.x series

3.3.3

Date: 14th March 2016.

Remove version string from templates. Thanks to @blag for the report and fixes. (#3878, #3913, #3912)
Fixes vertical html layout for BooleanField. Thanks to Mikalai Radchuk for the fix. (#3910)
Silenced deprecation warnings on Django 1.8. Thanks to Simon Charette for the fix. (#3903)
Internationalization for authtoken. Thanks to Michael Nacharov for the fix. (#3887, #3968)
Fix Token model as abstract when the authtoken application isn't declared. Thanks to Adam Thomas for the report. (#3860, #3858)
Improve Markdown version compatibility. Thanks to Michael J. Schultz for the fix. (#3604, #3842)
QueryParameterVersioning does not use DEFAULT_VERSION setting. Thanks to Brad Montgomery for the fix. (#3833)
Add an explicit on_delete on the models. Thanks to Mads Jensen for the fix. (#3832)
Fix DateField.to_representation to work with Python 2 unicode. Thanks to Mikalai Radchuk for the fix. (#3819)
Fixed TimeField not handling string times. Thanks to Areski Belaid for the fix. (#3809)
Avoid updates of Meta.extra_kwargs. Thanks to Kevin Massey for the report and fix. (#3805, #3804)
Fix nested validation error being rendered incorrectly. Thanks to Craig de Stigter for the fix. (#3801)
Document how to avoid CSRF and missing button issues with django-crispy-forms. Thanks to Emmanuelle Delescolle, José Padilla and Luis San Pablo for the report, analysis and fix. (#3787, #3636, #3637)
Improve Rest Framework Settings file setup time. Thanks to Miles Hutson for the report and Mads Jensen for the fix. (#3786, #3815)
Improve authtoken compatibility with Django 1.9. Thanks to S. Andrew Sheppard for the fix. (#3785)
Fix Min/MaxValueValidator transfer from a model's DecimalField. Thanks to Kevin Brown for the fix. (#3774)
Improve HTML title in the Browsable API. Thanks to Mike Lissner for the report and fix. (#3769)
Fix AutoFilterSet to inherit from default_filter_set. Thanks to Tom Linford for the fix. (#3753)
Fix transifex config to handle the new Chinese language codes. Thanks to @nypisces for the report and fix. (#3739)
DateTimeField does not handle empty values correctly. Thanks to Mick Parker for the report and fix. (#3731, #3726)
Raise error when setting a removed rest_framework setting. Thanks to Luis San Pablo for the fix. (#3715)
Add missing csrf_token in AdminRenderer post form. Thanks to Piotr Śniegowski for the fix. (#3703)
Refactored _get_reverse_relationships() to use correct to_field. Thanks to Benjamin Phillips for the fix. (#3696)
Document the use of get_queryset for RelatedField. Thanks to Ryan Hiebert for the fix. (#3605)
Fix empty pk detection in HyperlinkRelatedField.get_url. Thanks to @jslang for the fix (#3962)

3.3.2

Date: 14th December 2015.

ListField enforces input is a list. (#3513)
Fix regression hiding raw data form. (#3600, #3578)
Fix Python 3.5 compatibility. (#3534, #3626)
Allow setting a custom Django Paginator in pagination.PageNumberPagination. (#3631, #3684)
Fix relational fields without to_fields attribute. (#3635, #3634)
Fix template.render deprecation warnings for Django 1.9. (#3654)
Sort response headers in browsable API renderer. (#3655)
Use related_objects api for Django 1.9+. (#3656, #3252)
Add confirm modal when deleting. (#3228, #3662)
Reveal previously hidden AttributeErrors and TypeErrors while calling has_[object_]permissions. (#3668)
Make DRF compatible with multi template engine in Django 1.8. (#3672)
Update NestedBoundField to also handle empty string when rendering its form. (#3677)
Fix UUID validation to properly catch invalid input types. (#3687, #3679)
Fix caching issues. (#3628, #3701)
Fix Admin and API browser for views without a filter_class. (#3705, #3596, #3597)
Add app_name to rest_framework.urls. (#3714)
Improve authtoken's views to support url versioning. (#3718, #3723)

3.3.1

Date: 4th November 2015.

Resolve parsing bug when accessing request.POST (#3592)
Correctly deal with to_field referring to primary key. (#3593)
Allow filter HTML to render when no filter_class is defined. (#3560)
Fix admin rendering issues. (#3564, #3556)
Fix issue with DecimalValidator. (#3568)

3.3.0

Date: 28th October 2015.

HTML controls for filters. (#3315)
Forms API. (#3475)
AJAX browsable API. (#3410)
Added JSONField. (#3454)
Correctly map to_field when creating ModelSerializer relational fields. (#3526)
Include keyword arguments when mapping FilePathField to a serializer field. (#3536)
Map appropriate model error_messages on ModelSerializer uniqueness constraints. (#3435)
Include max_length constraint for ModelSerializer fields mapped from TextField. (#3509)
Added support for Django 1.9. (#3450, #3525)
Removed support for Django 1.5 & 1.6. (#3421, #3429)
Removed 'south' migrations. (#3495)

3.2.x series

3.2.5

Date: 27th October 2015.

Escape username in optional logout tag. (#3550)

3.2.4

Date: 21th September 2015.

Don't error on missing ViewSet.search_fields attribute. (#3324, #3323)
Fix allow_empty not working on serializers with many=True. (#3361, #3364)
Let DurationField accepts integers. (#3359)
Multi-level dictionaries not supported in multipart requests. (#3314)
Fix ListField truncation on HTTP PATCH (#3415, #2761)

3.2.3

Date: 24th August 2015.

Added html_cutoff and html_cutoff_text for limiting select dropdowns. (#3313)
Added regex style to SearchFilter. (#3316)
Resolve issues with setting blank HTML fields. (#3318) (#3321)
Correctly display existing 'select multiple' values in browsable API forms. (#3290)
Resolve duplicated validation message for IPAddressField. ([#3249[gh3249]) (#3250)
Fix to ensure admin renderer continues to work when pagination is disabled. (#3275)
Resolve error with LimitOffsetPagination when count=0, offset=0. (#3303)

3.2.2

Date: 13th August 2015.

Add display_value() method for use when displaying relational field select inputs. (#3254)
Fix issue with BooleanField checkboxes incorrectly displaying as checked. (#3258)
Ensure empty checkboxes properly set BooleanField to False in all cases. (#2776)
Allow WSGIRequest.FILES property without raising incorrect deprecated error. (#3261)
Resolve issue with rendering nested serializers in forms. (#3260)
Raise an error if user accidentally pass a serializer instance to a response, rather than data. (#3241)

3.2.1

Date: 7th August 2015.

Fix for relational select widgets rendering without any choices. (#3237)
Fix for 1, 0 rendering as true, false in the admin interface. #3227)
Fix for ListFields with single value in HTML form input. (#3238)
Allow request.FILES for compat with Django's HTTPRequest class. (#3239)

3.2.0

Date: 6th August 2015.

Add AdminRenderer. (#2926)
Add FilePathField. (#1854)
Add allow_empty to ListField. (#2250)
Support django-guardian 1.3. (#3165)
Support grouped choices. (#3225)
Support error forms in browsable API. (#3024)
Allow permission classes to customize the error message. (#2539)
Support source=<method> on hyperlinked fields. (#2690)
ListField(allow_null=True) now allows null as the list value, not null items in the list. (#2766)
ManyToMany() maps to allow_empty=False, ManyToMany(blank=True) maps to allow_empty=True. (#2804)
Support custom serialization styles for primary key fields. (#2789)
OPTIONS requests support nested representations. (#2915)
Set view.action == "metadata" for viewsets with OPTIONS requests. (#3115)
Support allow_blank on UUIDField. ([#3130][gh#3130])
Do not display view docstrings with 401 or 403 response codes. (#3216)
Resolve Django 1.8 deprecation warnings. (#2886)
Fix for DecimalField validation. (#3139)
Fix behavior of allow_blank=False when used with trim_whitespace=True. (#2712)
Fix issue with some field combinations incorrectly mapping to an invalid allow_blank argument. (#3011)
Fix for output representations with prefetches and modified querysets. (#2704, #2727)
Fix assertion error when CursorPagination is provided with certains invalid query parameters. (#2920)gh2920.
Fix UnicodeDecodeError when invalid characters included in header with TokenAuthentication. (#2928)
Fix transaction rollbacks with @non_atomic_requests decorator. (#3016)
Fix duplicate results issue with Oracle databases using SearchFilter. (#2935)
Fix checkbox alignment and rendering in browsable API forms. (#2783)
Fix for unsaved file objects which should use "url": null in the representation. (#2759)
Fix field value rendering in browsable API. (#2416)
Fix HStoreField to include allow_blank=True in DictField mapping. (#2659)
Numerous other cleanups, improvements to error messaging, private API & minor fixes.

3.1.x series

3.1.3

Date: 4th June 2015.

Add DurationField. (#2481, #2989)
Add format argument to UUIDField. (#2788, #3000)
MultipleChoiceField empties incorrectly on a partial update using multipart/form-data (#2993, #2894)
Fix a bug in options related to read-only RelatedField. (#2981, #2811)
Fix nested serializers with unique_together relations. (#2975)
Allow unexpected values for ChoiceField/MultipleChoiceField representations. (#2839, #2940)
Rollback the transaction on error if ATOMIC_REQUESTS is set. (#2887, #2034)
Set the action on a view when override_method regardless of its None-ness. (#2933)
DecimalField accepts 2E+2 as 200 and validates decimal place correctly. (#2948, #2947)
Support basic authentication with custom UserModel that change username. (#2952)
IPAddressField improvements. (#2747, #2618, #3008)
Improve DecimalField for easier subclassing. (#2695)

3.1.2

Date: 13rd May 2015.

DateField.to_representation can handle str and empty values. (#2656, #2687, #2869)
Use default reason phrases from HTTP standard. (#2764, #2763)
Raise error when ModelSerializer used with abstract model. (#2757, #2630)
Handle reversal of non-API view_name in HyperLinkedRelatedField (#2724, #2711)
Dont require pk strictly for related fields. (#2745, #2754)
Metadata detects null boolean field type. (#2762)
Proper handling of depth in nested serializers. (#2798)
Display viewset without paginator. (#2807)
Don't check for deprecated .model attribute in permissions (#2818)
Restrict integer field to integers and strings. (#2835, #2836)
Improve IntegerField to use compiled decimal regex. (#2853)
Prevent empty queryset to raise AssertionError. (#2862)
DjangoModelPermissions rely on get_queryset. (#2863)
Check AcceptHeaderVersioning with content negotiation in place. (#2868)
Allow DjangoObjectPermissions to use views that define get_queryset. (#2905)

3.1.1

Date: 23rd March 2015.

Security fix: Escape tab switching cookie name in browsable API.
Display input forms in browsable API if serializer_class is used, even when get_serializer method does not exist on the view. (#2743)
Use a password input for the AuthTokenSerializer. (#2741)
Fix missing anchor closing tag after next button. (#2691)
Fix lookup_url_kwarg handling in viewsets. (#2685, #2591)
Fix problem with importing rest_framework.views in apps.py (#2678)
LimitOffsetPagination raises TypeError if PAGE_SIZE not set (#2667, #2700)
German translation for min_value field error message references max_value. (#2645)
Remove MergeDict. (#2640)
Support serializing unsaved models with related fields. (#2637, #2641)
Allow blank/null on radio.html choices. (#2631)

Fix a bug where _closable_objects breaks pickling. (#1850, #2492)
Allow non-standard User models with Throttling. (#2524)
Support custom User.db_table in TokenAuthentication migration. (#2479)
Fix misleading AttributeError tracebacks on Request objects. (#2530, #2108)
ManyRelatedField.get_value clearing field on partial update. (#2475)
Removed '.model' shortcut from code. (#2486)
Fix detail_route and list_route mutable argument. (#2518)
Prefetching the user object when getting the token in TokenAuthentication. (#2519)

3.0.4

Date: 28th January 2015.

Django 1.8a1 support. (#2425, #2446, #2441)
Add DictField and support Django 1.8 HStoreField. (#2451, #2106)
Add UUIDField and support Django 1.8 UUIDField. (#2448, #2433, #2432)
BaseRenderer.render now raises NotImplementedError. (#2434)
Fix timedelta JSON serialization on Python 2.6. (#2430)
ResultDict and ResultList now appear as standard dict/list. (#2421)
Fix visible HiddenField in the HTML form of the web browsable API page. (#2410)
Use OrderedDict for RelatedField.choices. (#2408)
Fix ident format when using HTTP_X_FORWARDED_FOR. (#2401)
Fix invalid key with memcached while using throttling. (#2400)
Fix FileUploadParser with version 3.x. (#2399)
Fix the serializer inheritance. (#2388)
Fix caching issues with ReturnDict. (#2360)

3.0.3

Date: 8th January 2015.

Fix MinValueValidator on models.DateField. (#2369)
Fix serializer missing context when pagination is used. (#2355)
Namespaced router URLs are now supported by the DefaultRouter. (#2351)
required=False allows omission of value for output. (#2342)
Use textarea input for models.TextField. (#2340)
Use custom ListSerializer for pagination if required. (#2331, #2327)
Better behavior with null and '' for blank HTML fields. (#2330)
Ensure fields in exclude are model fields. (#2319)
Fix IntegerField and max_length argument incompatibility. (#2317)
Fix the YAML encoder for 3.0 serializers. (#2315, #2283)
Fix the behavior of empty HTML fields. (#2311, #1101)
Fix Metaclass attribute depth ignoring fields attribute. (#2287)
Fix format_suffix_patterns to work with Django's i18n_patterns. (#2278)
Ability to customize router URLs for custom actions, using url_path. (#2010)
Don't install Django REST Framework as egg. (#2386)

3.0.2

Date: 17th December 2014.

Ensure request.user is made available to response middleware. (#2155)
Client.logout() also cancels any existing force_authenticate. (#2218, #2259)
Extra assertions and better checks to preventing incorrect serializer API use. (#2228, #2234, #2262, #2263, #2266, #2267, #2289, #2291)
Fixed min_length message for CharField. (#2255)
Fix UnicodeDecodeError, which can occur on serializer repr. (#2270, #2279)
Fix empty HTML values when a default is provided. (#2280, #2294)
Fix SlugRelatedField raising UnicodeEncodeError when used as a multiple choice input. (#2290)

3.0.1

Date: 11th December 2014.

More helpful error message when the default Serializer create() fails. (#2013)
Raise error when attempting to save serializer if data is not valid. (#2098)
Fix FileUploadParser breaks with empty file names and multiple upload handlers. (#2109)
Improve BindingDict to support standard dict-functions. (#2135, #2163)
Add validate() to ListSerializer. (#2168, #2225, #2232)
Fix JSONP renderer failing to escape some characters. (#2169, #2195)
Add missing default style for FileField. (#2172)
Actions are required when calling ViewSet.as_view(). (#2175)
Add allow_blank to ChoiceField. (#2184, #2239)
Cosmetic fixes in the HTML renderer. (#2187)
Raise error if fields on serializer is not a list of strings. (#2193, #2213)
Improve checks for nested creates and updates. (#2194, #2196)
validated_attrs argument renamed to validated_data in Serializer create()/update(). (#2197)
Remove deprecated code to reflect the dropped Django versions. (#2200)
Better serializer errors for nested writes. (#2202, #2215)
Fix pagination and custom permissions incompatibility. (#2205)
Raise error if fields on serializer is not a list of strings. (#2213)
Add missing translation markers for relational fields. (#2231)
Improve field lookup behavior for dicts/mappings. (#2244, #2243)
Optimized hyperlinked PK. (#2242)

3.0.0

Date: 1st December 2014

For full details see the 3.0 release announcement.

For older release notes, please see the version 2.x documentation.