Updated tutorial for routers and resources.

docs/tutorial/6-resource-orientated-projects.md

@@ -1,36 +1,70 @@
-serializers.py
+## Registering Resources
-
-    class BlogPostSerializer(URLModelSerializer):
-        class Meta:
-            model = BlogPost
-
-    class CommentSerializer(URLModelSerializer):
-        class Meta:
-            model = Comment
 
 resources.py
 
-    class BlogPostResource(ModelResource):
+    from djangorestframework.routers import DefaultResourceRouter
-        serializer_class = BlogPostSerializer
+    from models import BlogPost
-        model = BlogPost
-        permissions = [AdminOrAnonReadonly()]
-        throttles = [AnonThrottle(rate='5/min')]
 
-    class CommentResource(ModelResource):
+    class BlogPostResource (ModelResource):
-        serializer_class = CommentSerializer
+        pass
-        model = Comment
-        permissions = [AdminOrAnonReadonly()]
-        throttles = [AnonThrottle(rate='5/min')]
 
-Now that we're using Resources rather than Views, we don't need to design the urlconf ourselves.  The conventions for wiring up resources into views and urls are handled automatically.  All we need to do is register the appropriate resources with a router, and let it do the rest.  Here's our re-wired `urls.py` file.
+    class CommentResource (ModelResource):
+        pass
 
-    from blog import resources
+    api = DefaultResourceRouter()
-    from djangorestframework.routers import DefaultRouter
+    api.register(BlogPost, BlogPostResource)
+    api.register(Comment, CommentResource)
 
-    router = DefaultRouter()
+urls.py
-    router.register(resources.BlogPostResource)
+
-    router.register(resources.CommentResource)
+    from resources import router
-    urlpatterns = router.urlpatterns
+
+    urlpatterns = api.urlpatterns
+
+### Do you need a serializer at all?
+
+In the preceding example, the `Serializer` classes don't define any custom values
+(yet). As a result, the default model serializer will be provided. If you are
+happy with the default serializer, you don't need to define a `Serializer`
+object at all -- you can register the resource without providing a `Serializer`
+description. The preceding example could be simplified to:
+
+    from djangorestframework.routers import DefaultResourceRouter
+    from models import BlogPost
+
+    router = DefaultResourceRouter()
+    router.register(BlogPost)
+    router.register(CommentPost)
+
+## ModelResource options
+
+*ModelResource.serializer_class*
+
+Defaults to `ModelSerializer`.
+
+*ModelResource.permissions*
+
+Defaults to `DEFAULT_PERMISSIONS`.
+
+*ModelResource.throttles*
+
+Defaults to `DEFAULT_THROTTLES`.
+
+*ModelResource.list_view_class*
+
+Defaults to `RootAPIView`.  Set to `ListAPIView` for read-only.
+
+*ModelResource.instance_view_class*
+
+Defaults to `InstanceAPIView`.  Set to `DetailAPIView` for read-only.
+
+*ModelResource.collection_name*
+
+If `None`, the model's `verbose_name_plural` will be used.
+
+*ModelResource.id_field_name*
+
+Defaults to `'pk'`.
 
 ## Trade-offs between views vs resources.
 
@@ -46,4 +80,4 @@ We've reached the end of our tutorial.  If you want to get more involved in the
 * Join the REST framework group, and help build the community.
 * Follow me [on Twitter](https://twitter.com/_tomchristie) and say hi.
 
-Now go build something great.
+Now go build something great.