2.0 Announcement

docs/api-guide/views.md

@@ -120,7 +120,9 @@ You won't typically need to override this method.
 
 REST framework also allows you to work with regular function based views. It provides a set of simple decorators that wrap your function based views to ensure they receive an instance of `Request` (rather than the usual Django `HttpRequest`) and allows them to return a `Response` (instead of a Django `HttpResponse`), and allow you to configure how the request is processed.
 
-### api_view(http_method_names)
+## @api_view()
+
+**Signature:** `@api_view(http_method_names)
 
 The core of this functionality is the `api_view` decorator, which takes a list of HTTP methods that your view should respond to. For example, this is how you would write a very simple view that just manually returns some data:
 
@@ -133,7 +135,9 @@ The core of this functionality is the `api_view` decorator, which takes a list o
 
 This view will use the default renderers, parsers, authentication classes etc specified in the [settings](settings).
 
-To override the default settings, REST framework provides a set of additional decorators which can be added to your views. These must come *after* (below) the `api_view` decorator. For example, to create a view that uses a [throttle](throttling) to ensure it can only be called once per day by a particular user, use the `throttle_classes` decorator, passing a list of throttle classes:
+## API policy decorators
+
+To override the default settings, REST framework provides a set of additional decorators which can be added to your views. These must come *after* (below) the `@api_view` decorator. For example, to create a view that uses a [throttle](throttling) to ensure it can only be called once per day by a particular user, use the `@throttle_classes` decorator, passing a list of throttle classes:
 
     from rest_framework.decorators import api_view, throttle_classes
     from rest_framework.throttling import UserRateThrottle
@@ -148,16 +152,15 @@ To override the default settings, REST framework provides a set of additional de
 
 These decorators correspond to the attributes set on `APIView` subclasses, described above.
 
-### @renderer_classes()
+The available decorators are:
 
-### @parser_classes()
-
-### @authentication_classes()
-
-### @throttle_classes()
-
-### @permission_classes()
+* `@renderer_classes(...)`
+* `@parser_classes(...)`
+* `@authentication_classes(...)`
+* `@throttle_classes(...)`
+* `@permission_classes(...)`
 
+Each of these decorators takes a single argument which must be a list or tuple of classes.
 
 [cite]: http://reinout.vanrees.org/weblog/2011/08/24/class-based-views-usage.html
 [cite2]: http://www.boredomandlaziness.org/2012/05/djangos-cbvs-are-not-mistake-but.html

docs/index.md

@@ -103,7 +103,7 @@ General guides to using REST framework.
 * [The Browsable API][browsableapi]
 * [REST, Hypermedia & HATEOAS][rest-hypermedia-hateoas]
 * [Contributing to REST framework][contributing]
-* [2.0 Migration Guide][migration]
+* [2.0 Announcement][rest-framework-2-announcement]
 * [Release Notes][release-notes]
 * [Credits][credits]
 
@@ -189,7 +189,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 [browsableapi]: topics/browsable-api.md
 [rest-hypermedia-hateoas]: topics/rest-hypermedia-hateoas.md
 [contributing]: topics/contributing.md
-[migration]: topics/migration.md
+[rest-framework-2-announcement]: topics/rest-framework-2-announcement.md
 [release-notes]: topics/release-notes.md
 [credits]: topics/credits.md
 

docs/template.html

@@ -93,7 +93,7 @@
                   <li><a href="{{ base_url }}/topics/browsable-api{{ suffix }}">The Browsable API</a></li>
                   <li><a href="{{ base_url }}/topics/rest-hypermedia-hateoas{{ suffix }}">REST, Hypermedia & HATEOAS</a></li>
                   <li><a href="{{ base_url }}/topics/contributing{{ suffix }}">Contributing to REST framework</a></li>
-                  <li><a href="{{ base_url }}/topics/migration{{ suffix }}">2.0 Migration Guide</a></li>
+                  <li><a href="{{ base_url }}/topics/rest-framework-2-announcement{{ suffix }}">2.0 Announcement</a></li>
                   <li><a href="{{ base_url }}/topics/release-notes{{ suffix }}">Release Notes</a></li>
                   <li><a href="{{ base_url }}/topics/credits{{ suffix }}">Credits</a></li>
                 </ul>

docs/topics/rest-framework-2-announcement.md

@@ -0,0 +1,88 @@
+# Django REST framework 2
+
+What it is, and why you should care
+
+> Most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result.
+>
+> — [Roy Fielding][cite]
+
+REST framework 2 is an almost complete reworking of the original framework, which comprehensivly addresses some of the original design issues.
+
+Because the latest version should be considered a re-release, rather than an incremental improvement, we've skipped a version, and called this release Django REST framework 2.0.
+
+This article is intended to give you a flavor of what REST framework 2 is, and why you might want to give it a try.
+
+## User feedback
+
+Before we get cracking, let's start with the hard sell, with a few bits of feedback from some early adopters…
+
+"Django REST framework 2 is beautiful. Some of the API design is worthy of @kennethreitz." - [Kit La Touche][quote1]
+
+"Since it's pretty much just Django, controlling things like URLs has been a breeze... I think [REST framework 2] has definitely got the right approach here; even simple things like being able to override a function called post to do custom work during rather than having to intimately know what happens during a post make a huge difference to your productivity." - [Ian Strachan][quote2]
+
+"I switched to the 2.0 branch and I don't regret it - fully refactored my code in another ½ day and it's *much* more to my tastes" - [Bruno Desthuilliers][quote3]
+
+Sounds good, right?  Let's get into some details...
+
+## Serialization
+
+REST framework 2 includes a totally re-worked serialization engine, that was initially intended as a replacement for Django's existing inflexible fixture serialization, and which meets the following design goals:
+
+* A declarative serialization API, that mirrors Django's `Forms`/`ModelForms` API.
+* Structural concerns are decoupled from encoding concerns.
+* Able to support rendering and parsing to many formats, including both machine-readable representations and HTML forms.
+* Validation that can be mapped to obvious and comprehensive error responses. 
+* Serializers that support both nested, flat, and partially-nested representations.
+* Relationships that can be expressed as primary keys, hyperlinks, slug fields, and other custom representations.
+
+Mapping between the internal state of the system and external representations of that state is the core concern of building Web APIs.  Designing serializers that allow the developer to do so in a flexible and obvious way is a deceptively difficult design task, and with the new serialization API we think we've pretty much nailed it.
+
+## Generic views
+
+When REST framework was initially released at the start of 2011, the current Django release was version 1.2.  REST framework included a backport of Django 1.3's upcoming `View` class, but it didn't take full advantage of the generic view implementations.
+
+With the new release the generic views in REST framework now tie in with Django's generic views.  The end result is that framework is clean, lightweight and easy to use.
+
+## Requests, Responses & Views
+
+REST framework 2 includes `Request` and `Response` classes, than are used in place of Django's existing `HttpRequest` and `HttpResponse` classes.  Doing so allows logic such as parsing the incoming request or rendering the outgoing response to be supported transparently by the framework.
+
+The `Request`/`Response` approach leads to a much cleaner API, less logic in the view itself, and a simple, obvious request-response cycle.
+
+REST framework 2 also allows you to work with both function-based and class-based views.  For simple API views all you need is a single `@api_view` decorator, and you're good to go.
+
+
+## API Design
+
+Pretty much every aspect of REST framework has been reworked, with the aim of ironing out some of the design flaws of the previous versions.  Each of the components of REST framework are cleanly decoupled, and can be used independantly of each-other, and there are no monolithic resource classes, overcomplicated mixin combinations, or opinionated serialization or URL routing decisions.
+
+## Documentation
+
+As you can see the documentation for REST framework has been radically improved.  It gets a completely new style, using markdown for the documentation source, and a bootstrap-based theme for the styling.
+
+In the author's opinion, using `markdown` for documentation is a much better option that `rst`.  It is intuitive and readable, and there is great tooling available, such as the [Mou][mou] editor for Mac OS X, which makes it easy and plesant to work.
+
+We're really pleased with how the docs style looks - it's simple and clean, and the docs build much more quickly than with the previous sphinx setup.  We'll miss being able to use the wonderful [Read the Docs][readthedocs] service, but we think it's a trade-off worth making.
+
+Developing REST framework's documentation builder into a fully-fledged reusable project is something that we have planned for a future date.
+
+## The Browseable API
+
+Django REST framework's most unique feature is the way it is able to serve up both machine-readable representations, and a fully browsable HTML representation to the same endpoints.
+
+Browseable Web APIs are easier to work with, visualize and debug, and generally makes it easier and more frictionless to inspect and work with.
+
+With REST framework 2, the browseable API gets a snazzy new bootstrap-based theme that looks great and is even nicer to work with.
+
+There are also some functionality improvments - actions such as as `POST` and `DELETE` will only display if the user has the appropriate permissions.
+
+## Summary
+
+In short, we've engineered the hell outta this thing, and we're incredibly proud of the result.
+
+[cite]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-724
+[quote1]: https://twitter.com/kobutsu/status/261689665952833536
+[quote2]: https://groups.google.com/d/msg/django-rest-framework/heRGHzG6BWQ/ooVURgpwVC0J
+[quote3]: https://groups.google.com/d/msg/django-rest-framework/flsXbvYqRoY/9lSyntOf5cUJ
+[mou]: http://mouapp.com/
+[readthedocs]: https://readthedocs.org/