django-rest-framework/docs/topics/2.3-announcement.md

REST framework 2.3 announcement

REST framework 2.3 is geared towards making it easier and quicker to build your Web APIs.

ViewSets & Routers

Easier Serializers

REST framework lets you be totally explict regarding how you want to represent relationships, allowing you to choose between styles such as hyperlinking or primary key relationships.

The ability to specify exactly how you want to represent relationships is powerful, but it also introduces complexity. In order to keep things more simple, REST framework now allows you to include reverse relationships simply by including the field name in the fields metadata of the serializer class.

For example, in REST framework 2.2, reverse relationships needed to be included explicitly on a serializer class.

class BlogSerializer(serializers.ModelSerializer):
    comments = serializers.PrimaryKeyRelatedField(many=True)

    class Meta:
        model = Blog
        fields = ('id', 'title', 'created', 'comments')

As of 2.3, you can simply include the field name, and the appropriate serializer field will automatically be used for the relationship.

class BlogSerializer(serializers.ModelSerializer):
    """
    Don't need to specify the 'comments' field explicitly anymore.
    """
    class Meta:
        model = Blog
        fields = ('id', 'title', 'created', 'comments')

Similarly, you can now easily include the primary key in hyperlinked relationships, simply by adding the field name to the metadata.

class BlogSerializer(serializers.HyperlinkedModelSerializer):
    """
    This is a hyperlinked serializer, which default to using
    a field named 'url' as the primary identifier.
    Note that we can now easily also add in the 'id' field.
    """
    class Meta:
        model = Blog
        fields = ('url', 'id', 'title', 'created', 'comments')

Simpler views

This release rationalises the API and implementation of the generic views, dropping the dependancy on Django's SingleObjectMixin and MultipleObjectMixin classes, removing a number of unneeded attributes, and generally making the implementation more obvious and easy to work with.

This improvement is reflected in improved documentation for the GenericAPIView base class, and should make it easier to determine how to override methods on the base class if you need to write customized subclasses.

---

API Changes

Simplified generic view classes

The functionality provided by SingleObjectAPIView and MultipleObjectAPIView base classes has now been moved into the base class GenericAPIView. The implementation of this base class is simple enough that providing subclasses for the base classes of detail and list views is somewhat unnecessary.

Additionally the base generic view no longer inherits from Django's SingleObjectMixin or MultipleObjectMixin classes, simplifying the implementation, and meaning you don't need to cross-reference across to Django's codebase.

Using the SingleObjectAPIView and MultipleObjectAPIView base classes continues to be supported, but will raise a PendingDeprecationWarning. You should instead simply use GenericAPIView as the base for any generic view subclasses.

Removed attributes

The following attributes and methods, were previously present as part of Django's generic view implementations, but were unneeded and unusedand have now been entirely removed.

• context_object_name
• get_context_data()
• get_context_object_name()

The following attributes and methods, which were previously present as part of Django's generic view implementations have also been entirely removed.

• paginator_class
• get_paginator()
• get_allow_empty()
• get_slug_field()

There may be cases when removing these bits of API might mean you need to write a little more code if your view has highly customized behavior, but generally we believe that providing a coarser-grained API will make the views easier to work with, and is the right trade-off to make for the vast majority of cases.

Note that the listed attributes and methods have never been a documented part of the REST framework API, and as such are not covered by the deprecation policy.

Simplified methods

The get_object and get_paginate_by methods no longer take an optional queryset argument. This makes overridden these methods more obvious, and a little more simple.

Using an optional queryset with these methods continues to be supported, but will raise a PendingDeprecationWarning.

The paginate_queryset method no longer takes a page_size argument, or returns a four-tuple of pagination information. Instead it simply takes a queryset argument, and either returns a page object with an appropraite page size, or returns None, if pagination is not configured for the view.

Using the page_size argument is still supported and will trigger the old-style return type, but will raise a PendingDeprecationWarning.

Deprecated attributes

The following attributes are used to control queryset lookup, and have all been moved into a pending deprecation state.

• pk_url_kwarg = 'pk'
• slug_url_kwarg = 'slug'
• slug_field = 'slug'

Their usage is replaced with a single attribute:

• lookup_field = 'pk'

This attribute is used both as the regex keyword argument in the URL conf, and as the model field to filter against when looking up a model instance. To use non-pk based lookup, simply set the lookup_field argument to an alternative field, and ensure that the keyword argument in the url conf matches the field name.

For example, a view with 'username' based lookup might look like this:

class UserDetail(generics.RetrieveAPIView):
    lookup_field = 'username'
    queryset = User.objects.all()
    serializer_class = UserSerializer

And would have the following entry in the urlconf:

 url(r'^users/(?P<username>\w+)/$', UserDetail.as_view()),

Usage of the old-style attributes continues to be supported, but will raise a PendingDeprecationWarning.

DecimalField

2.3 introduces a DecimalField serializer field, which returns Decimal instances.

For most cases APIs using model fields will behave as previously, however if you are using a custom renderer, not provided by REST framework, then you may now need to add support for rendering Decimal instances to your renderer implmentation.

View names and descriptions

The mechanics of how view names and descriptions are generated from the docstring and classname has been modified and cleaned up somewhat.

If you've been customizing this behavior, for example perhaps to use rst markup for the browseable API, then you'll need to take a look at the implementation to see what updates you need to make.

Note that the relevant methods have always been private APIs, and the docstrings called them out as intended to be deprecated.

ModelSerializers and reverse relationships

The support for adding reverse relationships to the fields option on a ModelSerializer class means that the get_related_field and get_nested_field method signatures have now changed.

In the unlikely event that you're providing a custom serializer class, and implementing these methods you should note the new call signature for both methods is now (self, model_field, related_model, to_many). For revese relationships model_field will be None.

The old-style signature will continue to function but will raise a PendingDeprecationWarning.

---

Other notes

More explicit style

The usage of model attribute in generic Views is still supported, but it's usage is being discouraged in favour of the setting the mode explict queryset and serializer_class attributes.

For example, the following is now the recommended style for using generic views:

class AccountListView(generics.RetrieveAPIView):
    queryset = MyModel.objects.all()
    serializer_class = MyModelSerializer

Using an explict queryset and serializer_class attributes makes the functioning of the view more clear than using the shortcut model attribute.

It also makes the usage of the get_queryset() or get_serializer_class() methods more obvious.

class AccountListView(generics.RetrieveAPIView):
    serializer_class = MyModelSerializer

    def get_queryset(self):
        """
        Determine the queryset dynamically, depending on the
        user making the request.

        Note that overriding this method follows on more obviously now
        that an explicit `queryset` attribute is the usual view style.
        """
        return self.user.accounts

Django 1.3 support

The 2.3 release series will be the last series to provide compatiblity with Django 1.3.

Version 2.2 API changes

All API changes in 2.2 that previously raised PendingDeprecationWarning will now raise a DeprecationWarning, which is loud by default.

What comes next?

The plan for the next few months is to concentrate on addressing outstanding tickets. 2.4 is likely to deal with relatively small refinements to the existing API.