From 2d44dc3f5490e93147ecedbd33b03f41a598b43a Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 2 May 2013 12:46:10 +0100 Subject: [PATCH] Update release notes --- docs/topics/2.3-announcement.md | 82 +++++++++++++++++++++++++-------- 1 file changed, 62 insertions(+), 20 deletions(-) diff --git a/docs/topics/2.3-announcement.md b/docs/topics/2.3-announcement.md index 5ca1f109c..c465b7743 100644 --- a/docs/topics/2.3-announcement.md +++ b/docs/topics/2.3-announcement.md @@ -1,9 +1,53 @@ # REST framework 2.3 announcement -REST framework 2.3 is geared towards making it easier and quicker to build your Web APIs. +REST framework 2.3 makes it even quicker and easier to build your Web APIs. -## ViewSets & Routers +## ViewSets and Routers +The 2.3 release introduces the [ViewSet][viewset] and [Router][router] classes. + +A viewset is simply a type of class based view that allows you to group multiple views into a single common class. + +Routers allow you to automatically determine the URLconf for your viewset classes. + +As an example of just how simple REST framework APIs can now be, here's an API written in a single `urls.py` module: + + """ + A REST framework API for viewing and editing users and groups. + """ + from django.conf.urls.defaults import url, patterns, include + from django.contrib.auth.models import User, Group + from rest_framework import viewsets, routers + + + # ViewSets define the view behavior. + class UserViewSet(viewsets.ModelViewSet): + model = User + + class GroupViewSet(viewsets.ModelViewSet): + model = Group + + + # Routers provide an easy way of automatically determining the URL conf + router = routers.DefaultRouter() + router.register(r'users', views.UserViewSet) + router.register(r'groups', views.GroupViewSet) + + + # Wire up our API using automatic URL routing. + # Additionally, we include login URLs for the browseable API. + urlpatterns = patterns('', + url(r'^', include(router.urls)), + url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) + ) + +The best place to get started with ViewSets and Routers is to take a look at the [newest section in the tutorial][part-6], which demonstrates their usage. + +## 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. ## Easier Serializers @@ -42,12 +86,6 @@ Similarly, you can now easily include the primary key in hyperlinked relationshi 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 @@ -119,7 +157,7 @@ Usage of the old-style attributes continues to be supported, but will raise a `P ## Simpler URL lookups -The `lookup_field` argument also replaces the `pk_url_kwarg`, `slug_url_kwarg`, and `slug_field` arguments when creating `HyperlinkedRelatedField` instances. +The `HyperlinkedRelatedField` class now takes a single optional `lookup_field` argument, that replaces the `pk_url_kwarg`, `slug_url_kwarg`, and `slug_field` arguments. For example, you might have a field that references it's relationship by a hyperlink based on a slug field: @@ -135,14 +173,6 @@ Usage of the old-style attributes continues to be supported, but will raise a `P 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. @@ -151,13 +181,21 @@ In the unlikely event that you're providing a custom serializer class, and imple The old-style signature will continue to function but will raise a `PendingDeprecationWarning`. +## View names and descriptions + +The mechanics of how the names and descriptions used in the browseable API are generated 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. + --- # 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. +The usage of `model` attribute in generic Views is still supported, but it's usage is generally being discouraged throughout the documentation, in favour of the setting the more explict `queryset` and `serializer_class` attributes. For example, the following is now the recommended style for using generic views: @@ -184,7 +222,7 @@ It also makes the usage of the `get_queryset()` or `get_serializer_class()` meth ## Django 1.3 support -The 2.3 release series will be the last series to provide compatiblity with Django 1.3. +The 2.3.x release series will be the last series to provide compatiblity with Django 1.3. ## Version 2.2 API changes @@ -192,4 +230,8 @@ All API changes in 2.2 that previously raised `PendingDeprecationWarning` will n ## 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. +The next few months should see a renewed focus on addressing outstanding tickets. The 2.4 release is currently planned for around August-September. + +[viewset]: ../api-guide/viewsets.md +[router]: ../api-guide/routers.md +[part-6]: ../tutorial/6-viewsets-and-routers.md