From f4d4d54e030addf64efe68f387b934262a3c173b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 8 Oct 2012 12:17:43 +0100 Subject: [PATCH] Adding migration and changelog docs --- docs/index.md | 10 ++- docs/template.html | 13 ++- .../{formoverloading.md => browserhacks.md} | 0 docs/topics/changelog.md | 8 +- docs/topics/migration.md | 85 +++++++++++++++++++ docs/topics/rest-hypermedia-hateoas.md | 2 +- rest_framework/renderers.py | 6 +- 7 files changed, 115 insertions(+), 9 deletions(-) rename docs/topics/{formoverloading.md => browserhacks.md} (100%) create mode 100644 docs/topics/migration.md diff --git a/docs/index.md b/docs/index.md index 44bd34a06..f9795c1a3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -98,9 +98,12 @@ The API guide is your complete reference manual to all the functionality provide General guides to using REST framework. * [CSRF][csrf] -* [Form overloading][formoverloading] +* [Browser hacks][browserhacks] * [Working with the Browsable API][browsableapi] +* [REST, Hypermedia & HATEOAS][rest-hypermedia-hateoas] * [Contributing to REST framework][contributing] +* [2.0 Migration Guide][migration] +* [Change Log][changelog] * [Credits][credits] ## Development @@ -173,7 +176,10 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [settings]: api-guide/settings.md [csrf]: topics/csrf.md -[formoverloading]: topics/formoverloading.md +[browserhacks]: topics/browserhacks.md [browsableapi]: topics/browsable-api.md +[rest-hypermedia-hateoas]: topics/rest-hypermedia-hateoas.md [contributing]: topics/contributing.md +[migration]: topics/migration.md +[changelog]: topics/changelog.md [credits]: topics/credits.md diff --git a/docs/template.html b/docs/template.html index c901cb9c0..cc2fd0198 100644 --- a/docs/template.html +++ b/docs/template.html @@ -72,9 +72,12 @@ Topics @@ -98,6 +101,12 @@
+
    {{ toc }} diff --git a/docs/topics/formoverloading.md b/docs/topics/browserhacks.md similarity index 100% rename from docs/topics/formoverloading.md rename to docs/topics/browserhacks.md diff --git a/docs/topics/changelog.md b/docs/topics/changelog.md index a4fd39e29..15fb63014 100644 --- a/docs/topics/changelog.md +++ b/docs/topics/changelog.md @@ -1,8 +1,11 @@ -# Release Notes +# Change Log ## 2.0.0 -**TODO:** Explain REST framework 2.0 +* **Fix all of the things.** +* For more information please see the [2.0 migration guide][migration]. + +--- ## 0.4.0 @@ -105,3 +108,4 @@ * Initial release. +[migration]: migration.md \ No newline at end of file diff --git a/docs/topics/migration.md b/docs/topics/migration.md new file mode 100644 index 000000000..f6a301b83 --- /dev/null +++ b/docs/topics/migration.md @@ -0,0 +1,85 @@ +# 2.0 Migration Guide + +REST framework 2.0 introduces a radical redesign of the core components, and a large number of backwards breaking changes. + +### Serialization redesign. + +REST framework's serialization and deserialization previously used a slightly odd combination of serializers for output, and Django Forms and Model Forms for input. The serialization core has been completely redesigned based on work that was originally intended for Django core. + +2.0's form-like serializers comprehensively address those issues, and are a much more flexible and clean solution to the problems around accepting both form-based and non-form based inputs. + +### Generic views improved. + +When REST framework 0.1 was released the current Django version was 1.2. REST framework included a backport of the Django 1.3's upcoming `View` class, but it didn't take full advantage of the generic view implementations. + +As of 2.0 the generic views in REST framework tie in much more cleanly and obviously with Django's existing codebase, and the mixin architecture is radically simplified. + +### Cleaner request-response cycle. + +REST framework 2.0's request-response cycle is now much less complex. + +* Responses inherit from `SimpleTemplateResponse`, allowing rendering to be delegated to the response, not handled by the view. +* Requests extend the regular `HttpRequest`, allowing authentication and parsing to be delegated to the request, not handled by the view. + +### Renamed attribnutes & classes. + +Various attributes and classes have been renamed in order to fit in better with Django's conventions. + +## Example: Blog Posts API + +Let's take a look at an example from the REST framework 0.4 documentation... + + from djangorestframework.resources import ModelResource + from djangorestframework.reverse import reverse + from blogpost.models import BlogPost, Comment + + + class BlogPostResource(ModelResource): + """ + A Blog Post has a *title* and *content*, and can be associated + with zero or more comments. + """ + model = BlogPost + fields = ('created', 'title', 'slug', 'content', 'url', 'comments') + ordering = ('-created',) + + def url(self, instance): + return reverse('blog-post', + kwargs={'key': instance.key}, + request=self.request) + + def comments(self, instance): + return reverse('comments', + kwargs={'blogpost': instance.key}, + request=self.request) + + + class CommentResource(ModelResource): + """ + A Comment is associated with a given Blog Post and has a + *username* and *comment*, and optionally a *rating*. + """ + model = Comment + fields = ('username', 'comment', 'created', 'rating', 'url', 'blogpost') + ordering = ('-created',) + + def blogpost(self, instance): + return reverse('blog-post', + kwargs={'key': instance.blogpost.key}, + request=self.request) + +There's a bit of a mix of concerns going on there. We've got some information about how the data should be serialized, such as the `fields` attribute, and some information about how it should be retrieved from the database - the `ordering` attribute. + +Let's start to re-write this for REST framework 2.0. + + from rest_framework import serializers + + class BlogPostSerializer(serializers.HyperlinkedModelSerializer): + model = BlogPost + fields = ('created', 'title', 'slug', 'content', 'url', 'comments') + + class CommentSerializer(serializers.HyperlinkedModelSerializer): + model = Comment + fields = ('username', 'comment', 'created', 'rating', 'url', 'blogpost') + + diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 46a4c9d72..3aa1ff5f3 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -20,7 +20,7 @@ the Design of Network-based Software Architectures][dissertation]. For a more thorough background, check out Klabnik's [Hypermedia API reading list][readinglist]. -# Building Hypermedia APIs with REST framework +## Building Hypermedia APIs with REST framework REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style. diff --git a/rest_framework/renderers.py b/rest_framework/renderers.py index 4157468fd..a776b0e2f 100644 --- a/rest_framework/renderers.py +++ b/rest_framework/renderers.py @@ -230,8 +230,11 @@ class DocumentingHTMLRenderer(BaseRenderer): if not getattr(view, 'get_serializer', None): return self.get_generic_content_form(view) + ##### + # TODO: This is a little bit of a hack. Actually we'd like to remove + # this and just render serializer fields to html directly. + # We need to map our Fields to Django's Fields. - # TODO: Remove this and just render serializer fields directly field_mapping = { serializers.FloatField: forms.FloatField, serializers.IntegerField: forms.IntegerField, @@ -252,7 +255,6 @@ class DocumentingHTMLRenderer(BaseRenderer): serializer = view.get_serializer(instance=obj) for k, v in serializer.get_fields(True).items(): - print k, v if getattr(v, 'readonly', True): continue