Release Early, Release Often
— Eric S. Raymond, The Cathedral and the Bazaar.
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. No major point releases are currently planned.
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
PendingDeprecationWarningwarnings 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.
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 | grep djangorestframework
Date: 12th June 2014
- Security fix: Escape request path when it is include as part of the login and logout links in the browsable API.
verbose_nameautomatically set for related fields on
- Fix nested serializers linked through a backward foreign key relation.
- Fix bad links for the
- Fix mediatype detection under Python 3.
- Web browseable API now offers blank option on dropdown when the field is not required.
APIExceptionrepresentation improved for logging purposes.
- Allow source="*" within nested serializers.
- Better support for custom oauth2 provider backends.
- Fix field validation if it's optional and has no value.
APIRequestFactoryto support arguments within the url string for GET.
- Allow three transport modes for access tokens when accessing a protected resource.
QueryDictencoding on request objects.
- Ensure throttle keys do not contain spaces, as those are invalid if using
Date: 6th March 2014
- Django 1.7 Support.
defaultargument when used with serializer relation fields.
- Display the media type of the content that is being displayed in the browsable API, rather than 'text/html'.
- Bugfix for
urlizetemplate failure when URL regex is matched, but value does not
urandomfor token generation.
- Only use
Vary: Acceptwhen more than one renderer exists.
Date: 15th January 2014
- Security fix:
OrderingFieldnow only allows ordering on readable serializer fields, or on fields explicitly specified using
ordering_fields. This prevents users being able to order by fields that are not visible in the API, and exploiting the ordering of sensitive data such as password hashes.
write_only = Truefields now display in the browsable API.
Date: 14th January 2014
write_onlyserializer field argument.
- JSON renderer now deals with objects that implement a dict-like interface.
- Fix compatiblity with newer versions of
- Bugfix: Refine behavior that calls model manager
all()across nested serializer relationships, preventing erronous behavior with some non-ORM objects, and preventing unneccessary queryset re-evaluations.
- Bugfix: Allow defaults on BooleanFields to be properly honored when values are not supplied.
- Bugfix: Prevent double-escaping of non-latin1 URL query params when appending
Date: 6th December 2013
- Add in choices information for ChoiceFields in response to
- Added status code category helper functions.
- Bugfix: Partial updates which erronously set a related field to
Nonenow correctly fail validation instead of raising an exception.
- Bugfix: Responses without any content no longer include an HTTP
- Bugfix: Correctly handle validation errors in PUT-as-create case, responding with 400.
Date: 15th November 2013
- Fix Django 1.6 exception API compatibility issue caused by
- Include errors in HTML forms in browsable API.
- Added JSON renderer support for numpy scalars.
transform_<fieldname>hooks on serializers for easily modifying field output.
- Allow serializers to be passed
HTMLFormRenderernow renders serializers directly to HTML without needing to create an intermediate form object.
- Added queryset aggregates to allowed fields in
- Bugfix: Fix decimal suppoprt with
- Bugfix: Fix submission of unicode in browsable API through raw data form.
Date: 11th September 2013
- Support customizable exception handling, using the
- Support customizable view name and description functions, using the
max_paginate_bygeneric view attribute.
cacheattribute to throttles to allow overriding of default cache.
- 'Raw data' tab in browsable API now contains pre-populated data.
- 'Raw data' and 'HTML form' tab preference in browseable API now saved between page views.
required=Trueargument fixed for boolean serializer fields.
client.force_authenticate(None)should also clear session info if it exists.
- Bugfix: Client sending empty string instead of file now clears
- Bugfix: Empty values on ChoiceFields with
required=Falsenow consistently return
- Bugfix: Clients setting
page_size=0now simply returns the default page size, instead of disabling pagination. [*]
[*] Note that the change in
page_size=0 behaviour fixes what is considered to be a bug in how clients can effect the pagination size. However if you were relying on this behavior you will need to add the following mixin to your list views in order to preserve the existing behavior.
class DisablePaginationMixin(object): def get_paginate_by(self, queryset=None): if self.request.QUERY_PARAMS[self.paginate_by_param] == '0': return None return super(DisablePaginationMixin, self).get_paginate_by(queryset)
Date: 16th August 2013
SessionAuthenticationto allow esier override for CSRF exemption.
- Remove 'Hold down "Control" message from help_text' widget messaging when not appropriate.
- Added admin configuration for auth tokens.
AnonRateThrottlefixed to not throttle authenticated users.
- Bugfix: Don't set
X-Throttle-Wait-Secondswhen throttle does not have
- Bugfix: Fixed
PATCHbutton title in browsable API.
- Bugfix: Fix issue with OAuth2 provider naive datetimes.
Date: 27th June 2013
trailing_slashoption to routers.
- Include support for
- Support wider range of default serializer validation when used with custom model fields.
- UTF-8 Support for browsable API descriptions.
- OAuth2 provider uses timezone aware datetimes when supported.
- Bugfix: Return error correctly when OAuth non-existent consumer occurs.
- Bugfix: Allow
FileUploadParserto correctly filename if provided as URL kwarg.
- Bugfix: Fix
Date: 3rd June 2013
- Serializer field
defaultargument may be a callable.
@actiondecorator now accepts a
request.usershould be still be accessible in renderer context if authentication fails.
- Bugfix: The
HyperlinkedIdentityFieldshould apply by default to the url field on the serializer.
HyperlinkedIdentityFieldshould continue to support
slug_field, in a pending deprecation state.
- Bugfix: Ensure we always return 404 instead of 500 if a lookup field cannot be converted to the correct lookup type. (Eg non-numeric
Date: 24th May 2013
- Serializer fields now support
OPTIONSrequests now return metadata about fields for
charsetnow properly included in
- Bugfix: Blank choice now added in browsable API on nullable relationships.
- Bugfix: Many to many relationships with
throughtables are now read-only.
- Bugfix: Serializer fields now respect model field args such as
- Bugfix: SlugField now performs slug validation.
- Bugfix: Lazy-translatable strings now properly serialized.
- Bugfix: Browsable API now supports bootswatch styles properly.
- Bugfix: HyperlinkedIdentityField now uses
Note: Responses now correctly include an appropriate charset on the
Content-Type header. For example:
application/json; charset=utf-8. If you have tests that check the content type of responses, you may need to update these accordingly.
Date: 16th May 2013
- Added SearchFilter
- Added OrderingFilter
- Added GenericViewSet
- Bugfix: Multiple
@linkmethods now allowed on viewsets.
- Bugfix: Fix API Root view issue with DjangoModelPermissions
Date: 8th May 2013
- Bugfix: Fix
- Bugfix: Fix
DjangoFilterBackendissue, failing when used on view with queryset attribute.
Date: 7th May 2013
- Bugfix: Fix breadcrumb rendering issue.
Date: 7th May 2013
- ViewSets and Routers.
- ModelSerializers support reverse relations in 'fields' option.
- HyperLinkedModelSerializers support 'id' field in 'fields' option.
- Cleaner generic views.
- Support for multiple filter classes.
- FileUploadParser support for raw file uploads.
- DecimalField support.
- Made Login template easier to restyle.
- Bugfix: Fix issue with depth>1 on ModelSerializer.
Note: See the 2.3 announcement for full details.
Date: 17th April 2013
- Loud failure when view does not return a
- Bugfix: Fix for Django 1.3 compatibility.
- Bugfix: Allow overridden
get_object()to work correctly.
Date: 4th April 2013
- OAuth2 authentication no longer requires unnecessary URL parameters in addition to the token.
- URL hyperlinking in browsable API now handles more cases correctly.
- Long HTTP headers in browsable API are broken in multiple lines when possible.
- Bugfix: Fix regression with DjangoFilterBackend not worthing correctly with single object views.
- Bugfix: OAuth should fail hard when invalid token used.
- Bugfix: Fix serializer potentially returning
Noneobject for models that define
Date: 26th March 2013
- Serializer support for bulk create and bulk update operations.
- Regression fix: Date and time fields return date/time objects by default. Fixes regressions caused by 2.2.2. See #743 for more details.
- Bugfix: Fix 500 error is OAuth not attempted with OAuthAuthentication class installed.
Serializer.save()now supports arbitrary keyword args which are passed through to the object
.save()method. Mixins use
force_updatewhere appropriate, resulting in one less database query.
Date: 13th March 2013
- OAuth 2 support.
- OAuth 1.0a support.
- Support X-HTTP-Method-Override header.
- Filtering backends are now applied to the querysets for object lookups as well as lists. (Eg you can use a filtering backend to control which objects should 404)
- Deal with error data nicely when deserializing lists of objects.
- Extra override hook to configure
DjangoModelPermissionsfor unauthenticated users.
- Bugfix: Fix regression which caused extra database query on paginated list views.
- Bugfix: Fix pk relationship bug for some types of 1-to-1 relations.
- Bugfix: Workaround for Django bug causing case where
Authtokencould be registered for cascade delete from
Usereven if not installed.
Date: 7th March 2013
- Bugfix: Fix None values for for
Date: 6th March 2013
- Support for custom input and output formats for
- Cleanup: Request authentication is no longer lazily evaluated, instead authentication is always run, which results in more consistent, obvious behavior. Eg. Supplying bad auth credentials will now always return an error response, even if no permissions are set on the view.
- Bugfix for serializer data being uncacheable with pickle protocol 0.
- Bugfixes for model field validation edge-cases.
- Bugfix for authtoken migration while using a custom user model and south.
Date: 22nd Feb 2013
- Security fix: Use
defusedxmlpackage to address XML parsing vulnerabilities.
- Raw data tab added to browsable API. (Eg. Allow for JSON input.)
- Added TimeField.
- Serializer fields can be mapped to any method that takes no args, or only takes kwargs which have defaults.
- Unicode support for view names/descriptions in browsable API.
- Bugfix: request.DATA should return an empty
QueryDictwith no data, not
- Bugfix: Remove unneeded field validation, which caused extra queries.
Security note: Following the disclosure of security vulnerabilities in Python's XML parsing libraries, use of the
XMLParser class now requires the
defusedxml package to be installed.
The security vulnerabilities only affect APIs which use the
XMLParser class, by enabling it in any views, or by having it set in the
DEFAULT_PARSER_CLASSES setting. Note that the
XMLParser class is not enabled by default, so this change should affect a minority of users.
Date: 13th Feb 2013
- Python 3 support.
- Added a
post_save()hook to the generic views.
- Allow serializers to handle dicts as well as objects.
ManyRelatedField()syntax in favor of
null=Trueon relations in favor of
blank=Trueon CharFields, just use
- Deprecate optional
objargument in permissions checks in favor of
- Deprecate implicit hyperlinked relations behavior.
- Bugfix: Fix broken DjangoModelPermissions.
- Bugfix: Allow serializer output to be cached.
- Bugfix: Fix styling on browsable API login.
- Bugfix: Fix issue with deserializing empty to-many relations.
- Bugfix: Ensure model field validation is still applied for ModelSerializer subclasses with an custom
Note: See the 2.2 announcement for full details.
Date: 26th Jan 2013
- Support proper 401 Unauthorized responses where appropriate, instead of always using 403 Forbidden.
- Support json encoding of timedelta objects.
includestyle URL patterns.
- Bugfix: Fix issues with custom pagination serializers.
- Bugfix: Nested serializers now accept
- Bugfix: Return proper validation errors when incorrect types supplied for relational fields.
- Bugfix: Support nullable FKs with
- Bugfix: Don't call custom validation methods if the field has an error.
Note: If the primary authentication class is
BasicAuthentication, a view will now correctly return 401 responses to unauthenticated access, with an appropriate
WWW-Authenticate header, instead of 403 responses.
Date: 14th Jan 2013
django.utils.simplejsonin favor of Python 2.6's built-in json module.
editable=Falsefields now default to read-only.
- Bugfix: PK fields now only default to read-only if they are an AutoField or if
- Bugfix: Validation errors instead of exceptions when serializers receive incorrect types.
- Bugfix: Validation errors instead of exceptions when related fields receive incorrect types.
- Bugfix: Handle ObjectDoesNotExist exception when serializing null reverse one-to-one
Note: Prior to 2.1.16, The Decimals would render in JSON using floating point if
simplejson was installed, but otherwise render using string notation. Now that use of
simplejson has been deprecated, Decimals will consistently render using string notation. See #582 for more details.
Date: 3rd Jan 2013
- Remove unused internal
- Tweak behavior of hyperlinked fields with an explicit format suffix.
- Relation changes are now persisted in
.save()instead of in
- Bugfix: Fix issue with FileField raising exception instead of validation error when files=None.
- Bugfix: Partial updates should not set default values if field is not included.
Date: 31st Dec 2012
- Bugfix: ModelSerializers now include reverse FK fields on creation.
- Bugfix: Model fields with
- Bugfix: Nested serializers now support nullable relationships.
Note: From 2.1.14 onwards, relational fields move out of the
fields.py module and into the new
relations.py module, in order to separate them from regular data type fields, such as
This change will not affect user code, so long as it's following the recommended import style of
from rest_framework import serializers and referring to fields using the style
Date: 28th Dec 2012
- Support configurable
- Bugfix: Related fields now respect the required flag, and may be required=False.
Date: 21st Dec 2012
- Bugfix: Fix bug that could occur using ChoiceField.
- Bugfix: Fix exception in browsable API on DELETE.
- Bugfix: Fix issue where pk was was being set to a string if set by URL kwarg.
Date: 17th Dec 2012
- Bugfix: Fix issue with M2M fields in browsable API.
Date: 17th Dec 2012
- Bugfix: Ensure read-only fields don't have model validation applied.
- Bugfix: Fix hyperlinked fields in paginated results.
Date: 11th Dec 2012
- Bugfix: Fix broken nested serialization.
- Bugfix: Fix
Meta.fieldsonly working as tuple not as list.
- Bugfix: Edge case if unnecessarily specifying
required=Falseon read only field.
Date: 8th Dec 2012
- Fix for creating nullable Foreign Keys with
''as well as
null=<bool>related field option.
Date: 7th Dec 2012
- Serializers now properly support nullable Foreign Keys.
- Serializer validation now includes model field validation, such as uniqueness constraints.
- Support 'true' and 'false' string values for BooleanField.
- Added pickle support for serialized data.
source='dotted.notation'style for nested serializers.
- Bugfix: Fix
RegexFieldto work with
Date: 23rd Nov 2012
- Bugfix: Unfix DjangoModelPermissions. (I am a doofus.)
Date: 23rd Nov 2012
- Bugfix: Fix DjangoModelPermissions.
Date: 22nd Nov 2012
- Support for partial updates with serializers.
- Serializer performance improvements.
obtain_token_viewto get tokens when using
- Bugfix: Django 1.5 configurable user support for
Date: 16th Nov 2012
ImageField. For use with
- Support for
- Support for clients overriding the pagination page sizes. Use the
PAGINATE_BY_PARAMsetting or set the
paginate_by_paramattribute on a generic view.
- 201 Responses now return a 'Location' header.
- Bugfix: Serializer fields now respect
Date: 9th Nov 2012
- Filtering support.
- Bugfix: Support creation of objects with reverse M2M relations.
Date: 7th Nov 2012
- Support use of HTML exception templates. Eg.
- Hyperlinked fields take optional
- Bugfix: Deal with optional trailing slashes properly when generating breadcrumbs.
- Bugfix: Make textareas same width as other fields in browsable API.
- Private API change:
.get_serializernow uses same
dataordering as serializer initialization.
Date: 5th Nov 2012
datakeyword args have their position swapped.
querysetargument is now optional on writable model fields.
- Hyperlinked related fields optionally take
- Support Django's cache framework.
- Minor field improvements. (Don't stringify dicts, more robust many-pk fields.)
- Bugfix: Support choice field in Browsable API.
- Bugfix: Related fields with
read_only=Truedo not require a
API-incompatible changes: Please read this thread regarding the
data keyword args before updating to 2.1.0.
Date: 2nd Nov 2012
- Fix issues with pk related fields in the browsable API.
Date: 1st Nov 2012
- Add support for relational fields in the browsable API.
- Added SlugRelatedField and ManySlugRelatedField.
- If PUT creates an instance return '201 Created', instead of '200 OK'.
Date: 30th Oct 2012
- Fix all of the things. (Well, almost.)
- For more information please see the 2.0 announcement.
- Supports Django 1.5.
- Fixes issues with 'HEAD' method.
- Allow views to specify template used by TemplateRenderer
- More consistent error responses
- Some serializer fixes
- Fix internet explorer ajax behavior
- Minor xml and yaml fixes
- Improve setup (e.g. use staticfiles, not the defunct ADMIN_MEDIA_PREFIX)
- Sensible absolute URL generation, not using hacky set_script_prefix
- Added DjangoModelPermissions class to support
staticfilesfor css files.
- Easier to override. Won't conflict with customized admin styles (e.g. grappelli)
- Templates are now nicely namespaced.
- Allows easier overriding.
- Drop implied 'pk' filter if last arg in urlconf is unnamed.
- Too magical. Explicit is better than implicit.
- Saner template variable auto-escaping.
- Tidier setup.py
- Updated for URLObject 2.0
- Bug with PerUserThrottling when user contains unicode chars.
- Fix 403 for POST and PUT from the UI with UserLoggedInAuthentication (#115)
- serialize_model method in serializer.py may cause wrong value (#73)
- Fix Error when clicking OPTIONS button (#146)
- And many other fixes
- Remove short status codes
- Zen of Python: "There should be one-- and preferably only one --obvious way to do it."
- get_name, get_description become methods on the view - makes them overridable.
- Improved model mixin API - Hooks for build_query, get_instance_data, get_model, get_queryset, get_ordering
- [not documented]
- JSONP Support
- Bugfixes, including support for latest markdown release
- Fix broken IsAdminUser permission.
- OPTIONS support.
- Drop mentions of Blog, BitBucket.
- Fix some throttling bugs.
X-Throttleheader on throttling.
- Support for nesting resources on related models.
- Throttling support complete.
- Couple of simple bugfixes over 0.2.0
Big refactoring changes since 0.1.0, ask on the discussion group if anything isn't clear. The public API has been massively cleaned up. Expect it to be fairly stable from here on in.
Resourcebecomes decoupled into
Resource, your views should now inherit from
The handler functions on views
.get() .put() .post()etc, no longer have the
self.CONTENTinside a view to access the deserialized, validated content. Use
self.userinside a view to access the authenticated user.
anon_allowed_methodsare now defunct. if a method is defined, it's available. The
permissionsattribute on a
Viewis now used to provide generic permissions checking. Use permission classes such as
IsUserOrIsAnonReadOnlyto set the permissions.
authentication. Class names change to
renderers. Class names change to
The mixin classes have been nicely refactored, the basic mixins are now
ResourceMixinYou can reuse these mixin classes individually without using the
- Final build before pulling in all the refactoring changes for 0.2, in case anyone needs to hang on to 0.1.
- Initial release.