From 8f3931e02d0f0ba803075ca65dc8617ee959456f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 15 Jan 2013 17:50:39 +0000 Subject: Update docs --- docs/tutorial/6-resource-orientated-projects.md | 119 +++++++++++++++--------- 1 file changed, 76 insertions(+), 43 deletions(-) (limited to 'docs') diff --git a/docs/tutorial/6-resource-orientated-projects.md b/docs/tutorial/6-resource-orientated-projects.md index 9ee599ae..97fb5d69 100644 --- a/docs/tutorial/6-resource-orientated-projects.md +++ b/docs/tutorial/6-resource-orientated-projects.md @@ -1,49 +1,93 @@ # Tutorial 6 - Resources -Resource classes are just View classes that don't have any handler methods bound to them. The actions on a resource are defined, +REST framework includes an abstraction for dealing with resources, that allows the developer to concentrate on modelling the state and interactions of the API, and leave the URL construction to be handled automatically, based on common conventions. -This allows us to: +To work with resources, we can use either the `Resource` class, which does not define any default handlers, or the `ModelResource` class, which provides a default set of CRUD operations. -* Encapsulate common behaviour across a class of views, in a single Resource class. -* Separate out the actions of a Resource from the specifics of how those actions should be bound to a particular set of URLs. +Resource classes are very similar to class based views, except that they provide operations such as `read`, or `update`, and not HTTP method handlers such as `get` or `put`. Resources are only bound to HTTP method handlers at the last moment, when they are instantiated into views, typically by using a `Router` class which handles the complexities of defining the URL conf for you. -## Refactoring to use Resources, not Views +## Refactoring to use Resources, instead of Views -For instance, we can re-write our 4 sets of views into something more compact... +Let's take our current set of views, and refactor them into resources. +We'll remove our existing `views.py` module, and instead create a `resources.py` -resources.py +Our `UserResource` is simple, since we just want the default model CRUD behavior, so we inherit from `ModelResource` and include the same set of attributes we used for the corresponding view classes. - class BlogPostResource(ModelResource): - serializer_class = BlogPostSerializer - model = BlogPost - permissions_classes = (permissions.IsAuthenticatedOrReadOnly,) - throttle_classes = (throttles.UserRateThrottle,) + class UserResource(resources.ModelResource): + model = User + serializer_class = UserSerializer + +There's a little bit more work to do for the `SnippetResource`. Again, we want the +default set of CRUD behavior, but we also want to include an endpoint for snippet highlights. + + class SnippetResource(resources.ModelResource): + model = Snippet + serializer_class = SnippetSerializer + permission_classes = (permissions.IsAuthenticatedOrReadOnly, + IsOwnerOrReadOnly,) + + @link(renderer_classes=[renderers.StaticHTMLRenderer]) + def highlight(self, request, *args, **kwargs): + snippet = self.get_object() + return Response(snippet.highlighted) + + def pre_save(self, obj): + obj.owner = self.request.user + +Notice that we've used the `@link` decorator for the `highlight` endpoint. This decorator can be used for non-CRUD endpoints that are "safe" operations that do not change server state. Using `@link` indicates that we want to use a `GET` method for these operations. For non-CRUD operations we can also use the `@action` decorator for any operations that change server state, which ensures that the `POST` method will be used for the operation. - class CommentResource(ModelResource): - serializer_class = CommentSerializer - model = Comment - permissions_classes = (permissions.IsAuthenticatedOrReadOnly,) - throttle_classes = (throttles.UserRateThrottle,) ## Binding Resources to URLs explicitly -The handler methods only get bound to the actions when we define the URLConf. Here's our urls.py: - comment_root = CommentResource.as_view(actions={ +The handler methods only get bound to the actions when we define the URLConf. +To see what's going on under the hood let's first explicitly create a set of views from our resources. + +In the `urls.py` file we first need to bind our resources to concrete views. + + snippet_list = SnippetResource.as_view(actions={ + 'get': 'list', + 'post': 'create' + }) + snippet_detail = SnippetResource.as_view(actions={ + 'get': 'retrieve', + 'put': 'update', + 'delete': 'destroy' + }) + snippet_highlight = SnippetResource.as_view(actions={ + 'get': 'highlight' + }) + user_list = UserResource.as_view(actions={ 'get': 'list', 'post': 'create' }) - comment_instance = CommentInstance.as_view(actions={ + user_detail = UserResource.as_view(actions={ 'get': 'retrieve', 'put': 'update', 'delete': 'destroy' }) - ... # And for blog post - - urlpatterns = patterns('blogpost.views', - url(r'^$', comment_root), - url(r'^(?P[0-9]+)$', comment_instance) - ... # And for blog post - ) + +We've now got a set of views exactly as we did before, that we can register with the URL conf. + +Replace the remainder of the `urls.py` file with the following: + + urlpatterns = format_suffix_patterns(patterns('snippets.views', + url(r'^$', 'api_root'), + url(r'^snippets/$', + snippet_list, + name='snippet-list'), + url(r'^snippets/(?P[0-9]+)/$', + snippet_detail, + name='snippet-detail'), + url(r'^snippets/(?P[0-9]+)/highlight/$', + snippet_highlight, + name='snippet-highlight'), + url(r'^users/$', + user_list, + name='user-list'), + url(r'^users/(?P[0-9]+)/$', + user_detail, + name='user-detail') + )) ## Using Routers @@ -52,25 +96,14 @@ Right now that hasn't really saved us a lot of code. However, now that we're us from blog import resources from rest_framework.routers import DefaultRouter - router = DefaultRouter() - router.register(resources.BlogPostResource) - router.register(resources.CommentResource) + router = DefaultRouter(include_root=True, include_format_suffixes=True) + router.register(resources.SnippetResource) + router.register(resources.UserResource) urlpatterns = router.urlpatterns ## Trade-offs between views vs resources. -Writing resource-oriented code can be a good thing. It helps ensure that URL conventions will be consistent across your APIs, and minimises the amount of code you need to write. - -The trade-off is that the behaviour is less explict. It can be more difficult to determine what code path is being followed, or where to override some behaviour. - -## Onwards and upwards. - -We've reached the end of our tutorial. If you want to get more involved in the REST framework project, here's a few places you can start: - -* Contribute on GitHub by reviewing issues, and submitting issues or pull requests. -* Join the REST framework group, and help build the community. -* Follow me [on Twitter][twitter] and say hi. +Writing resource-oriented code can be a good thing. It helps ensure that URL conventions will be consistent across your APIs, minimises the amount of code you need to write, and allows you to concentrate on the interactions and representations your API provides rather than the specifics of the URL conf. -**Now go build some awesome things.** +That doesn't mean it's always the right approach to take. There's a similar set of trade-offs to consider as when using class-based views. Using resources is less explicit than building your views individually. -[twitter]: https://twitter.com/_tomchristie -- cgit v1.2.3 From 4a7139e41d2500776c30e663c1cebce74b49270d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 15 Jan 2013 21:49:24 +0000 Subject: Tweaks --- docs/tutorial/6-resource-orientated-projects.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/tutorial/6-resource-orientated-projects.md b/docs/tutorial/6-resource-orientated-projects.md index 97fb5d69..019371d7 100644 --- a/docs/tutorial/6-resource-orientated-projects.md +++ b/docs/tutorial/6-resource-orientated-projects.md @@ -44,23 +44,25 @@ To see what's going on under the hood let's first explicitly create a set of vie In the `urls.py` file we first need to bind our resources to concrete views. - snippet_list = SnippetResource.as_view(actions={ + from snippets import resources + + snippet_list = resources.SnippetResource.as_view({ 'get': 'list', 'post': 'create' }) - snippet_detail = SnippetResource.as_view(actions={ + snippet_detail = resources.SnippetResource.as_view({ 'get': 'retrieve', 'put': 'update', 'delete': 'destroy' }) - snippet_highlight = SnippetResource.as_view(actions={ + snippet_highlight = resources.SnippetResource.as_view({ 'get': 'highlight' }) - user_list = UserResource.as_view(actions={ + user_list = resources.UserResource.as_view({ 'get': 'list', 'post': 'create' }) - user_detail = UserResource.as_view(actions={ + user_detail = resources.UserResource.as_view({ 'get': 'retrieve', 'put': 'update', 'delete': 'destroy' @@ -93,12 +95,12 @@ Replace the remainder of the `urls.py` file with the following: Right now that hasn't really saved us a lot of code. However, now that we're using Resources rather than Views, we actually don't need to design the urlconf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using `Router` classes. 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. - from blog import resources + from snippets import resources from rest_framework.routers import DefaultRouter - router = DefaultRouter(include_root=True, include_format_suffixes=True) - router.register(resources.SnippetResource) - router.register(resources.UserResource) + router = DefaultRouter() + router.register('snippets', resources.SnippetResource) + router.register('users', resources.UserResource) urlpatterns = router.urlpatterns ## Trade-offs between views vs resources. -- cgit v1.2.3 From 4c6396108704d38f534a16577de59178b1d0df3b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 17 Jan 2013 12:30:28 +0000 Subject: Tweak resource docs --- docs/tutorial/6-resource-orientated-projects.md | 66 ++++++++----------------- 1 file changed, 21 insertions(+), 45 deletions(-) (limited to 'docs') diff --git a/docs/tutorial/6-resource-orientated-projects.md b/docs/tutorial/6-resource-orientated-projects.md index 019371d7..37ab1419 100644 --- a/docs/tutorial/6-resource-orientated-projects.md +++ b/docs/tutorial/6-resource-orientated-projects.md @@ -42,65 +42,41 @@ Notice that we've used the `@link` decorator for the `highlight` endpoint. This The handler methods only get bound to the actions when we define the URLConf. To see what's going on under the hood let's first explicitly create a set of views from our resources. -In the `urls.py` file we first need to bind our resources to concrete views. +In the `urls.py` file we first need to bind our resource classes into a set of concrete views. - from snippets import resources + from snippets.resources import SnippetResource, UserResource + + snippet_list = SnippetResource.as_view({'get': 'list', 'post': 'create'}) + snippet_detail = SnippetResource.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) + snippet_highlight = SnippetResource.as_view({'get': 'highlight'}) + user_list = UserResource.as_view({'get': 'list', 'post': 'create'}) + user_detail = UserResource.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) - snippet_list = resources.SnippetResource.as_view({ - 'get': 'list', - 'post': 'create' - }) - snippet_detail = resources.SnippetResource.as_view({ - 'get': 'retrieve', - 'put': 'update', - 'delete': 'destroy' - }) - snippet_highlight = resources.SnippetResource.as_view({ - 'get': 'highlight' - }) - user_list = resources.UserResource.as_view({ - 'get': 'list', - 'post': 'create' - }) - user_detail = resources.UserResource.as_view({ - 'get': 'retrieve', - 'put': 'update', - 'delete': 'destroy' - }) - -We've now got a set of views exactly as we did before, that we can register with the URL conf. - -Replace the remainder of the `urls.py` file with the following: +Notice how create multiple views onto a single resource class, by binding the http methods to the required action for each view. + +Now that we've bound our resources into concrete views, that we can register the views with the URL conf as usual. urlpatterns = format_suffix_patterns(patterns('snippets.views', url(r'^$', 'api_root'), - url(r'^snippets/$', - snippet_list, - name='snippet-list'), - url(r'^snippets/(?P[0-9]+)/$', - snippet_detail, - name='snippet-detail'), - url(r'^snippets/(?P[0-9]+)/highlight/$', - snippet_highlight, - name='snippet-highlight'), - url(r'^users/$', - user_list, - name='user-list'), - url(r'^users/(?P[0-9]+)/$', - user_detail, - name='user-detail') + url(r'^snippets/$', snippet_list, name='snippet-list'), + url(r'^snippets/(?P[0-9]+)/$', snippet_detail, name='snippet-detail'), + url(r'^snippets/(?P[0-9]+)/highlight/$', snippet_highlight, name='snippet-highlight'), + url(r'^users/$', user_list, name='user-list'), + url(r'^users/(?P[0-9]+)/$', user_detail, name='user-detail') )) ## Using Routers -Right now that hasn't really saved us a lot of code. However, now that we're using Resources rather than Views, we actually don't need to design the urlconf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using `Router` classes. 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. +Now that we're using Resources rather than Views, we actually don't need to design the URL conf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using `Router` classes. 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. from snippets import resources from rest_framework.routers import DefaultRouter router = DefaultRouter() - router.register('snippets', resources.SnippetResource) - router.register('users', resources.UserResource) + router.register(r'^snippets/', resources.SnippetResource, 'snippet') + router.register(r'^users/', resources.UserResource, 'user') urlpatterns = router.urlpatterns ## Trade-offs between views vs resources. -- cgit v1.2.3 From e9092e14207958832a86258fcb3740fb76dbcbe0 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 30 Mar 2013 16:54:22 +0000 Subject: Initial API documentation --- docs/viewsets-routers.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 docs/viewsets-routers.md (limited to 'docs') diff --git a/docs/viewsets-routers.md b/docs/viewsets-routers.md new file mode 100644 index 00000000..84ccb10b --- /dev/null +++ b/docs/viewsets-routers.md @@ -0,0 +1,107 @@ +# ViewSets & Routers + +> Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your index... a resourceful route declares them in a single line of code. + +— [Ruby on Rails Documentation][cite] + +Some Web frameworks such as Rails provide functionality for automatically determining how the URLs for an application should be mapped to the logic that deals with handling incoming requests. + +Conversely, Django stops short of automatically generating URLs, and requires you to explicitly manage your URL configuration. + +REST framework adds support for automatic URL routing, which provides you with a simple, quick and consistent way of wiring your view logic to a set of URLs. + +# ViewSets + +Django REST framework allows you to combine the logic for a set of related views in a single class, called a `ViewSet`. In other frameworks you may also find conceptually similar implementations named something like 'Resources' or 'Controllers'. + +A `ViewSet` class is simply **a type of class-based View, that does not provide any method handlers** such as `.get()` or `.post()`, and instead provides actions such as `.list()` and `.create()`. + +The method handlers for a `ViewSet` are only bound to the corresponding actions at the point of finalizing the view, using the `.as_view()` method. + +Typically, rather than exlicitly registering the views in a viewset in the urlconf, you'll register the viewset with a router class, that automatically determines the urlconf for you. + +## Example + +Let's define a simple viewset that can be used to listing or retrieving all the users in the system. + + class UserViewSet(ViewSet): + """ + A simple ViewSet that for listing or retrieving users. + """ + queryset = User.objects.all() + + def list(self, request): + serializer = UserSerializer(self.queryset, many=True) + return Response(serializer.data) + + def retrieve(self, request, pk=None): + user = get_object_or_404(self.queryset, pk=pk) + serializer = UserSerializer(user) + return Response(serializer.data) + +If we need to, we can bind this viewset into two seperate views, like so: + + user_list = UserViewSet.as_view({'get': 'list'}) + user_detail = UserViewSet.as_view({'get': 'retrieve'}) + +Typically we wouldn't do this, but would instead register the viewset with a router, and allow the urlconf to be automatically generated. + +# API Reference + +## ViewSet + +The `ViewSet` class inherits from `APIView`. You can use any of the standard attributes such as `permission_classes`, `authentication_classes` in order to control the API policy on the viewset. + +The `ViewSet` class does not provide any implementations of actions. In order to use a `ViewSet` class you'll override the class and define the action implementations explicitly. + +## ModelViewSet + +The `ModelViewSet` class inherits from `GenericAPIView` and includes implementations for various actions, by mixing in the behavior of the + +The actions provided by the `ModelViewSet` class are `.list()`, `.retrieve()`, `.create()`, `.update()`, and `.destroy()`. + +## ReadOnlyModelViewSet + +The `ReadOnlyModelViewSet` class also inherits from `GenericAPIView`. As with `ModelViewSet` it also includes implementations for various actions, but unlike `ModelViewSet` only provides the 'read-only' actions, `.list()` and `.retrieve()`. + +# Custom ViewSet base classes + +Any standard `View` class can be turned into a `ViewSet` class by mixing in `ViewSetMixin`. You can use this to define your own base classes. + +For example, the definition of `ModelViewSet` looks like this: + + class ModelViewSet(mixins.CreateModelMixin, + mixins.RetrieveModelMixin, + mixins.UpdateModelMixin, + mixins.DestroyModelMixin, + mixins.ListModelMixin, + viewsets.ViewSetMixin, + generics.GenericAPIView): + """ + A viewset that provides actions for `create`, `retrieve`, + `update`, `destroy` and `list` actions. + + To use it, override the class and set the `.queryset` + and `.serializer_class` attributes. + """ + pass + +By creating your own base `ViewSet` classes, you can provide common behavior that can be reused in multiple views across your API. + +Note the that `ViewSetMixin` class can also be applied to the standard Django `View` class if you want to use REST framework's automatic routing, but don't want to use it's permissions, authentication and other API policies. + +--- + +# Routers + +Routers provide a convenient and simple shortcut for wiring up your application's URLs. + + router = routers.DefaultRouter() + router.register('^/', APIRoot, 'api-root') + router.register('^users/', UserViewSet, 'user') + router.register('^groups/', GroupViewSet, 'group') + router.register('^accounts/', AccountViewSet, 'account') + + urlpatterns = router.urlpatterns + +[cite]: http://guides.rubyonrails.org/routing.html \ No newline at end of file -- cgit v1.2.3 From 97aa0239163868af40b0a5660c48b54bd7656ad6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 30 Mar 2013 17:22:52 +0000 Subject: Updating tutorial --- docs/tutorial/6-resource-orientated-projects.md | 69 ++++++++++++++----------- 1 file changed, 38 insertions(+), 31 deletions(-) (limited to 'docs') diff --git a/docs/tutorial/6-resource-orientated-projects.md b/docs/tutorial/6-resource-orientated-projects.md index 37ab1419..9c8a218f 100644 --- a/docs/tutorial/6-resource-orientated-projects.md +++ b/docs/tutorial/6-resource-orientated-projects.md @@ -1,27 +1,25 @@ -# Tutorial 6 - Resources +# Tutorial 6 - ViewSets & Routers -REST framework includes an abstraction for dealing with resources, that allows the developer to concentrate on modelling the state and interactions of the API, and leave the URL construction to be handled automatically, based on common conventions. +REST framework includes an abstraction for dealing with `ViewSets`, that allows the developer to concentrate on modelling the state and interactions of the API, and leave the URL construction to be handled automatically, based on common conventions. -To work with resources, we can use either the `Resource` class, which does not define any default handlers, or the `ModelResource` class, which provides a default set of CRUD operations. +`ViewSet` classes are almost the same thing as `View` classes, except that they provide operations such as `read`, or `update`, and not method handlers such as `get` or `put`. -Resource classes are very similar to class based views, except that they provide operations such as `read`, or `update`, and not HTTP method handlers such as `get` or `put`. Resources are only bound to HTTP method handlers at the last moment, when they are instantiated into views, typically by using a `Router` class which handles the complexities of defining the URL conf for you. +A `ViewSet` class is only bound to a set of method handlers at the last moment, when it is instantiated into a set of views, typically by using a `Router` class which handles the complexities of defining the URL conf for you. -## Refactoring to use Resources, instead of Views +## Refactoring to use ViewSets -Let's take our current set of views, and refactor them into resources. -We'll remove our existing `views.py` module, and instead create a `resources.py` +Let's take our current set of views, and refactor them into view sets. -Our `UserResource` is simple, since we just want the default model CRUD behavior, so we inherit from `ModelResource` and include the same set of attributes we used for the corresponding view classes. +First of all let's refactor our `UserListView` and `UserDetailView` views into a single `UserViewSet`. We can remove the two views, and replace then with a single class: - class UserResource(resources.ModelResource): - model = User + class UserViewSet(viewsets.ModelViewSet): + queryset = User.objects.all() serializer_class = UserSerializer -There's a little bit more work to do for the `SnippetResource`. Again, we want the -default set of CRUD behavior, but we also want to include an endpoint for snippet highlights. +Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighlight` view classes. We can remove the three views, and again replace them with a single class. - class SnippetResource(resources.ModelResource): - model = Snippet + class SnippetViewSet(viewsets.ModelViewSet): + queryset = Snippet.objects.all() serializer_class = SnippetSerializer permission_classes = (permissions.IsAuthenticatedOrReadOnly, IsOwnerOrReadOnly,) @@ -34,25 +32,27 @@ default set of CRUD behavior, but we also want to include an endpoint for snippe def pre_save(self, obj): obj.owner = self.request.user -Notice that we've used the `@link` decorator for the `highlight` endpoint. This decorator can be used for non-CRUD endpoints that are "safe" operations that do not change server state. Using `@link` indicates that we want to use a `GET` method for these operations. For non-CRUD operations we can also use the `@action` decorator for any operations that change server state, which ensures that the `POST` method will be used for the operation. +Notice that we've used the `@link` decorator for the `highlight` method. +This decorator can be used to add custom endpoints, other than the standard `create`/`update`/`delete` endpoints. +The `@link` decorator will -## Binding Resources to URLs explicitly +## Binding ViewSets to URLs explicitly The handler methods only get bound to the actions when we define the URLConf. -To see what's going on under the hood let's first explicitly create a set of views from our resources. +To see what's going on under the hood let's first explicitly create a set of views from our ViewSets. -In the `urls.py` file we first need to bind our resource classes into a set of concrete views. +In the `urls.py` file we first need to bind our `ViewSet` classes into a set of concrete views. from snippets.resources import SnippetResource, UserResource - snippet_list = SnippetResource.as_view({'get': 'list', 'post': 'create'}) - snippet_detail = SnippetResource.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) - snippet_highlight = SnippetResource.as_view({'get': 'highlight'}) - user_list = UserResource.as_view({'get': 'list', 'post': 'create'}) - user_detail = UserResource.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) + snippet_list = SnippetViewSet.as_view({'get': 'list', 'post': 'create'}) + snippet_detail = SnippetViewSet.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) + snippet_highlight = SnippetViewSet.as_view({'get': 'highlight'}) + user_list = UserViewSet.as_view({'get': 'list', 'post': 'create'}) + user_detail = UserViewSet.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) -Notice how create multiple views onto a single resource class, by binding the http methods to the required action for each view. +Notice how we're creating multiple views from each `ViewSet` class, by binding the http methods to the required action for each view. Now that we've bound our resources into concrete views, that we can register the views with the URL conf as usual. @@ -67,21 +67,28 @@ Now that we've bound our resources into concrete views, that we can register the ## Using Routers -Now that we're using Resources rather than Views, we actually don't need to design the URL conf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using `Router` classes. All we need to do is register the appropriate resources with a router, and let it do the rest. +Now that we're using `ViewSet` classes rather than `View` classes, we actually don't need to design the URL conf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using a `Router` class. All we need to do is register the appropriate view sets with a router, and let it do the rest. Here's our re-wired `urls.py` file. - from snippets import resources + from snippets import views from rest_framework.routers import DefaultRouter + # Create a router and register our views and view sets with it. router = DefaultRouter() - router.register(r'^snippets/', resources.SnippetResource, 'snippet') - router.register(r'^users/', resources.UserResource, 'user') + router.register(r'^/', views.api_root) + router.register(r'^snippets/', views.SnippetViewSet, 'snippet') + router.register(r'^users/', views.UserViewSet, 'user') + + # The urlconf is determined automatically by the router. urlpatterns = router.urlpatterns + + # Add format suffixes to all our URL patterns. + urlpatterns = format_suffix_patterns(urlpatterns) -## Trade-offs between views vs resources. +## Trade-offs between views vs viewsets. -Writing resource-oriented code can be a good thing. It helps ensure that URL conventions will be consistent across your APIs, minimises the amount of code you need to write, and allows you to concentrate on the interactions and representations your API provides rather than the specifics of the URL conf. +Using view sets can be a really useful abstraction. It helps ensure that URL conventions will be consistent across your API, minimises the amount of code you need to write, and allows you to concentrate on the interactions and representations your API provides rather than the specifics of the URL conf. -That doesn't mean it's always the right approach to take. There's a similar set of trade-offs to consider as when using class-based views. Using resources is less explicit than building your views individually. +That doesn't mean it's always the right approach to take. There's a similar set of trade-offs to consider as when using class-based views instead of function based views. Using view sets is less explicit than building your views individually. -- cgit v1.2.3 From ec076a00786c6b89a55b6ffe2556bb3b777100f5 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 31 Mar 2013 11:36:58 +0100 Subject: Add viewsets/routers to indexs etc --- docs/api-guide/viewsets-routers.md | 109 ++++++++++++++++++++++++ docs/index.md | 4 + docs/template.html | 2 + docs/tutorial/6-resource-orientated-projects.md | 94 -------------------- docs/tutorial/6-viewsets-and-routers.md | 94 ++++++++++++++++++++ docs/viewsets-routers.md | 107 ----------------------- 6 files changed, 209 insertions(+), 201 deletions(-) create mode 100644 docs/api-guide/viewsets-routers.md delete mode 100644 docs/tutorial/6-resource-orientated-projects.md create mode 100644 docs/tutorial/6-viewsets-and-routers.md delete mode 100644 docs/viewsets-routers.md (limited to 'docs') diff --git a/docs/api-guide/viewsets-routers.md b/docs/api-guide/viewsets-routers.md new file mode 100644 index 00000000..817e1b8f --- /dev/null +++ b/docs/api-guide/viewsets-routers.md @@ -0,0 +1,109 @@ + + +# ViewSets & Routers + +> Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your index... a resourceful route declares them in a single line of code. +> +> — [Ruby on Rails Documentation][cite] + +Some Web frameworks such as Rails provide functionality for automatically determining how the URLs for an application should be mapped to the logic that deals with handling incoming requests. + +Conversely, Django stops short of automatically generating URLs, and requires you to explicitly manage your URL configuration. + +REST framework adds support for automatic URL routing, which provides you with a simple, quick and consistent way of wiring your view logic to a set of URLs. + +# ViewSets + +Django REST framework allows you to combine the logic for a set of related views in a single class, called a `ViewSet`. In other frameworks you may also find conceptually similar implementations named something like 'Resources' or 'Controllers'. + +A `ViewSet` class is simply **a type of class-based View, that does not provide any method handlers** such as `.get()` or `.post()`, and instead provides actions such as `.list()` and `.create()`. + +The method handlers for a `ViewSet` are only bound to the corresponding actions at the point of finalizing the view, using the `.as_view()` method. + +Typically, rather than exlicitly registering the views in a viewset in the urlconf, you'll register the viewset with a router class, that automatically determines the urlconf for you. + +## Example + +Let's define a simple viewset that can be used to listing or retrieving all the users in the system. + + class UserViewSet(ViewSet): + """ + A simple ViewSet that for listing or retrieving users. + """ + queryset = User.objects.all() + + def list(self, request): + serializer = UserSerializer(self.queryset, many=True) + return Response(serializer.data) + + def retrieve(self, request, pk=None): + user = get_object_or_404(self.queryset, pk=pk) + serializer = UserSerializer(user) + return Response(serializer.data) + +If we need to, we can bind this viewset into two seperate views, like so: + + user_list = UserViewSet.as_view({'get': 'list'}) + user_detail = UserViewSet.as_view({'get': 'retrieve'}) + +Typically we wouldn't do this, but would instead register the viewset with a router, and allow the urlconf to be automatically generated. + +# API Reference + +## ViewSet + +The `ViewSet` class inherits from `APIView`. You can use any of the standard attributes such as `permission_classes`, `authentication_classes` in order to control the API policy on the viewset. + +The `ViewSet` class does not provide any implementations of actions. In order to use a `ViewSet` class you'll override the class and define the action implementations explicitly. + +## ModelViewSet + +The `ModelViewSet` class inherits from `GenericAPIView` and includes implementations for various actions, by mixing in the behavior of the + +The actions provided by the `ModelViewSet` class are `.list()`, `.retrieve()`, `.create()`, `.update()`, and `.destroy()`. + +## ReadOnlyModelViewSet + +The `ReadOnlyModelViewSet` class also inherits from `GenericAPIView`. As with `ModelViewSet` it also includes implementations for various actions, but unlike `ModelViewSet` only provides the 'read-only' actions, `.list()` and `.retrieve()`. + +# Custom ViewSet base classes + +Any standard `View` class can be turned into a `ViewSet` class by mixing in `ViewSetMixin`. You can use this to define your own base classes. + +For example, the definition of `ModelViewSet` looks like this: + + class ModelViewSet(mixins.CreateModelMixin, + mixins.RetrieveModelMixin, + mixins.UpdateModelMixin, + mixins.DestroyModelMixin, + mixins.ListModelMixin, + viewsets.ViewSetMixin, + generics.GenericAPIView): + """ + A viewset that provides actions for `create`, `retrieve`, + `update`, `destroy` and `list` actions. + + To use it, override the class and set the `.queryset` + and `.serializer_class` attributes. + """ + pass + +By creating your own base `ViewSet` classes, you can provide common behavior that can be reused in multiple views across your API. + +Note the that `ViewSetMixin` class can also be applied to the standard Django `View` class if you want to use REST framework's automatic routing, but don't want to use it's permissions, authentication and other API policies. + +--- + +# Routers + +Routers provide a convenient and simple shortcut for wiring up your application's URLs. + + router = routers.DefaultRouter() + router.register('^/', APIRoot, 'api-root') + router.register('^users/', UserViewSet, 'user') + router.register('^groups/', GroupViewSet, 'group') + router.register('^accounts/', AccountViewSet, 'account') + + urlpatterns = router.urlpatterns + +[cite]: http://guides.rubyonrails.org/routing.html \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 4c2720c8..469a5885 100644 --- a/docs/index.md +++ b/docs/index.md @@ -86,6 +86,7 @@ The tutorial will walk you through the building blocks that make up REST framewo * [3 - Class based views][tut-3] * [4 - Authentication & permissions][tut-4] * [5 - Relationships & hyperlinked APIs][tut-5] +* [6 - ViewSets & Routers][tut-6] ## API Guide @@ -95,6 +96,7 @@ The API guide is your complete reference manual to all the functionality provide * [Responses][response] * [Views][views] * [Generic views][generic-views] +* [ViewSets and Routers][viewsets-routers] * [Parsers][parsers] * [Renderers][renderers] * [Serializers][serializers] @@ -197,11 +199,13 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [tut-3]: tutorial/3-class-based-views.md [tut-4]: tutorial/4-authentication-and-permissions.md [tut-5]: tutorial/5-relationships-and-hyperlinked-apis.md +[tut-6]: tutorial/6-viewsets-and-routers.md [request]: api-guide/requests.md [response]: api-guide/responses.md [views]: api-guide/views.md [generic-views]: api-guide/generic-views.md +[viewsets-routers]: api-guide/viewsets-routers.md [parsers]: api-guide/parsers.md [renderers]: api-guide/renderers.md [serializers]: api-guide/serializers.md diff --git a/docs/template.html b/docs/template.html index 7e929762..aec3ecc9 100644 --- a/docs/template.html +++ b/docs/template.html @@ -62,6 +62,7 @@
  • 3 - Class based views
  • 4 - Authentication and permissions
  • 5 - Relationships and hyperlinked APIs
    • +
  • 6 - ViewSets and Routers
  • @@ -71,6 +72,7 @@
  • Responses
  • Views
  • Generic views
    • +
  • ViewSets and Routers
  • Parsers
  • Renderers
  • Serializers
    • diff --git a/docs/tutorial/6-resource-orientated-projects.md b/docs/tutorial/6-resource-orientated-projects.md deleted file mode 100644 index 9c8a218f..00000000 --- a/docs/tutorial/6-resource-orientated-projects.md +++ /dev/null @@ -1,94 +0,0 @@ -# Tutorial 6 - ViewSets & Routers - -REST framework includes an abstraction for dealing with `ViewSets`, that allows the developer to concentrate on modelling the state and interactions of the API, and leave the URL construction to be handled automatically, based on common conventions. - -`ViewSet` classes are almost the same thing as `View` classes, except that they provide operations such as `read`, or `update`, and not method handlers such as `get` or `put`. - -A `ViewSet` class is only bound to a set of method handlers at the last moment, when it is instantiated into a set of views, typically by using a `Router` class which handles the complexities of defining the URL conf for you. - -## Refactoring to use ViewSets - -Let's take our current set of views, and refactor them into view sets. - -First of all let's refactor our `UserListView` and `UserDetailView` views into a single `UserViewSet`. We can remove the two views, and replace then with a single class: - - class UserViewSet(viewsets.ModelViewSet): - queryset = User.objects.all() - serializer_class = UserSerializer - -Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighlight` view classes. We can remove the three views, and again replace them with a single class. - - class SnippetViewSet(viewsets.ModelViewSet): - queryset = Snippet.objects.all() - serializer_class = SnippetSerializer - permission_classes = (permissions.IsAuthenticatedOrReadOnly, - IsOwnerOrReadOnly,) - - @link(renderer_classes=[renderers.StaticHTMLRenderer]) - def highlight(self, request, *args, **kwargs): - snippet = self.get_object() - return Response(snippet.highlighted) - - def pre_save(self, obj): - obj.owner = self.request.user - -Notice that we've used the `@link` decorator for the `highlight` method. -This decorator can be used to add custom endpoints, other than the standard `create`/`update`/`delete` endpoints. - -The `@link` decorator will - -## Binding ViewSets to URLs explicitly - -The handler methods only get bound to the actions when we define the URLConf. -To see what's going on under the hood let's first explicitly create a set of views from our ViewSets. - -In the `urls.py` file we first need to bind our `ViewSet` classes into a set of concrete views. - - from snippets.resources import SnippetResource, UserResource - - snippet_list = SnippetViewSet.as_view({'get': 'list', 'post': 'create'}) - snippet_detail = SnippetViewSet.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) - snippet_highlight = SnippetViewSet.as_view({'get': 'highlight'}) - user_list = UserViewSet.as_view({'get': 'list', 'post': 'create'}) - user_detail = UserViewSet.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) - -Notice how we're creating multiple views from each `ViewSet` class, by binding the http methods to the required action for each view. - -Now that we've bound our resources into concrete views, that we can register the views with the URL conf as usual. - - urlpatterns = format_suffix_patterns(patterns('snippets.views', - url(r'^$', 'api_root'), - url(r'^snippets/$', snippet_list, name='snippet-list'), - url(r'^snippets/(?P[0-9]+)/$', snippet_detail, name='snippet-detail'), - url(r'^snippets/(?P[0-9]+)/highlight/$', snippet_highlight, name='snippet-highlight'), - url(r'^users/$', user_list, name='user-list'), - url(r'^users/(?P[0-9]+)/$', user_detail, name='user-detail') - )) - -## Using Routers - -Now that we're using `ViewSet` classes rather than `View` classes, we actually don't need to design the URL conf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using a `Router` class. All we need to do is register the appropriate view sets with a router, and let it do the rest. - -Here's our re-wired `urls.py` file. - - from snippets import views - from rest_framework.routers import DefaultRouter - - # Create a router and register our views and view sets with it. - router = DefaultRouter() - router.register(r'^/', views.api_root) - router.register(r'^snippets/', views.SnippetViewSet, 'snippet') - router.register(r'^users/', views.UserViewSet, 'user') - - # The urlconf is determined automatically by the router. - urlpatterns = router.urlpatterns - - # Add format suffixes to all our URL patterns. - urlpatterns = format_suffix_patterns(urlpatterns) - -## Trade-offs between views vs viewsets. - -Using view sets can be a really useful abstraction. It helps ensure that URL conventions will be consistent across your API, minimises the amount of code you need to write, and allows you to concentrate on the interactions and representations your API provides rather than the specifics of the URL conf. - -That doesn't mean it's always the right approach to take. There's a similar set of trade-offs to consider as when using class-based views instead of function based views. Using view sets is less explicit than building your views individually. - diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md new file mode 100644 index 00000000..9c8a218f --- /dev/null +++ b/docs/tutorial/6-viewsets-and-routers.md @@ -0,0 +1,94 @@ +# Tutorial 6 - ViewSets & Routers + +REST framework includes an abstraction for dealing with `ViewSets`, that allows the developer to concentrate on modelling the state and interactions of the API, and leave the URL construction to be handled automatically, based on common conventions. + +`ViewSet` classes are almost the same thing as `View` classes, except that they provide operations such as `read`, or `update`, and not method handlers such as `get` or `put`. + +A `ViewSet` class is only bound to a set of method handlers at the last moment, when it is instantiated into a set of views, typically by using a `Router` class which handles the complexities of defining the URL conf for you. + +## Refactoring to use ViewSets + +Let's take our current set of views, and refactor them into view sets. + +First of all let's refactor our `UserListView` and `UserDetailView` views into a single `UserViewSet`. We can remove the two views, and replace then with a single class: + + class UserViewSet(viewsets.ModelViewSet): + queryset = User.objects.all() + serializer_class = UserSerializer + +Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighlight` view classes. We can remove the three views, and again replace them with a single class. + + class SnippetViewSet(viewsets.ModelViewSet): + queryset = Snippet.objects.all() + serializer_class = SnippetSerializer + permission_classes = (permissions.IsAuthenticatedOrReadOnly, + IsOwnerOrReadOnly,) + + @link(renderer_classes=[renderers.StaticHTMLRenderer]) + def highlight(self, request, *args, **kwargs): + snippet = self.get_object() + return Response(snippet.highlighted) + + def pre_save(self, obj): + obj.owner = self.request.user + +Notice that we've used the `@link` decorator for the `highlight` method. +This decorator can be used to add custom endpoints, other than the standard `create`/`update`/`delete` endpoints. + +The `@link` decorator will + +## Binding ViewSets to URLs explicitly + +The handler methods only get bound to the actions when we define the URLConf. +To see what's going on under the hood let's first explicitly create a set of views from our ViewSets. + +In the `urls.py` file we first need to bind our `ViewSet` classes into a set of concrete views. + + from snippets.resources import SnippetResource, UserResource + + snippet_list = SnippetViewSet.as_view({'get': 'list', 'post': 'create'}) + snippet_detail = SnippetViewSet.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) + snippet_highlight = SnippetViewSet.as_view({'get': 'highlight'}) + user_list = UserViewSet.as_view({'get': 'list', 'post': 'create'}) + user_detail = UserViewSet.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) + +Notice how we're creating multiple views from each `ViewSet` class, by binding the http methods to the required action for each view. + +Now that we've bound our resources into concrete views, that we can register the views with the URL conf as usual. + + urlpatterns = format_suffix_patterns(patterns('snippets.views', + url(r'^$', 'api_root'), + url(r'^snippets/$', snippet_list, name='snippet-list'), + url(r'^snippets/(?P[0-9]+)/$', snippet_detail, name='snippet-detail'), + url(r'^snippets/(?P[0-9]+)/highlight/$', snippet_highlight, name='snippet-highlight'), + url(r'^users/$', user_list, name='user-list'), + url(r'^users/(?P[0-9]+)/$', user_detail, name='user-detail') + )) + +## Using Routers + +Now that we're using `ViewSet` classes rather than `View` classes, we actually don't need to design the URL conf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using a `Router` class. All we need to do is register the appropriate view sets with a router, and let it do the rest. + +Here's our re-wired `urls.py` file. + + from snippets import views + from rest_framework.routers import DefaultRouter + + # Create a router and register our views and view sets with it. + router = DefaultRouter() + router.register(r'^/', views.api_root) + router.register(r'^snippets/', views.SnippetViewSet, 'snippet') + router.register(r'^users/', views.UserViewSet, 'user') + + # The urlconf is determined automatically by the router. + urlpatterns = router.urlpatterns + + # Add format suffixes to all our URL patterns. + urlpatterns = format_suffix_patterns(urlpatterns) + +## Trade-offs between views vs viewsets. + +Using view sets can be a really useful abstraction. It helps ensure that URL conventions will be consistent across your API, minimises the amount of code you need to write, and allows you to concentrate on the interactions and representations your API provides rather than the specifics of the URL conf. + +That doesn't mean it's always the right approach to take. There's a similar set of trade-offs to consider as when using class-based views instead of function based views. Using view sets is less explicit than building your views individually. + diff --git a/docs/viewsets-routers.md b/docs/viewsets-routers.md deleted file mode 100644 index 84ccb10b..00000000 --- a/docs/viewsets-routers.md +++ /dev/null @@ -1,107 +0,0 @@ -# ViewSets & Routers - -> Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your index... a resourceful route declares them in a single line of code. - -— [Ruby on Rails Documentation][cite] - -Some Web frameworks such as Rails provide functionality for automatically determining how the URLs for an application should be mapped to the logic that deals with handling incoming requests. - -Conversely, Django stops short of automatically generating URLs, and requires you to explicitly manage your URL configuration. - -REST framework adds support for automatic URL routing, which provides you with a simple, quick and consistent way of wiring your view logic to a set of URLs. - -# ViewSets - -Django REST framework allows you to combine the logic for a set of related views in a single class, called a `ViewSet`. In other frameworks you may also find conceptually similar implementations named something like 'Resources' or 'Controllers'. - -A `ViewSet` class is simply **a type of class-based View, that does not provide any method handlers** such as `.get()` or `.post()`, and instead provides actions such as `.list()` and `.create()`. - -The method handlers for a `ViewSet` are only bound to the corresponding actions at the point of finalizing the view, using the `.as_view()` method. - -Typically, rather than exlicitly registering the views in a viewset in the urlconf, you'll register the viewset with a router class, that automatically determines the urlconf for you. - -## Example - -Let's define a simple viewset that can be used to listing or retrieving all the users in the system. - - class UserViewSet(ViewSet): - """ - A simple ViewSet that for listing or retrieving users. - """ - queryset = User.objects.all() - - def list(self, request): - serializer = UserSerializer(self.queryset, many=True) - return Response(serializer.data) - - def retrieve(self, request, pk=None): - user = get_object_or_404(self.queryset, pk=pk) - serializer = UserSerializer(user) - return Response(serializer.data) - -If we need to, we can bind this viewset into two seperate views, like so: - - user_list = UserViewSet.as_view({'get': 'list'}) - user_detail = UserViewSet.as_view({'get': 'retrieve'}) - -Typically we wouldn't do this, but would instead register the viewset with a router, and allow the urlconf to be automatically generated. - -# API Reference - -## ViewSet - -The `ViewSet` class inherits from `APIView`. You can use any of the standard attributes such as `permission_classes`, `authentication_classes` in order to control the API policy on the viewset. - -The `ViewSet` class does not provide any implementations of actions. In order to use a `ViewSet` class you'll override the class and define the action implementations explicitly. - -## ModelViewSet - -The `ModelViewSet` class inherits from `GenericAPIView` and includes implementations for various actions, by mixing in the behavior of the - -The actions provided by the `ModelViewSet` class are `.list()`, `.retrieve()`, `.create()`, `.update()`, and `.destroy()`. - -## ReadOnlyModelViewSet - -The `ReadOnlyModelViewSet` class also inherits from `GenericAPIView`. As with `ModelViewSet` it also includes implementations for various actions, but unlike `ModelViewSet` only provides the 'read-only' actions, `.list()` and `.retrieve()`. - -# Custom ViewSet base classes - -Any standard `View` class can be turned into a `ViewSet` class by mixing in `ViewSetMixin`. You can use this to define your own base classes. - -For example, the definition of `ModelViewSet` looks like this: - - class ModelViewSet(mixins.CreateModelMixin, - mixins.RetrieveModelMixin, - mixins.UpdateModelMixin, - mixins.DestroyModelMixin, - mixins.ListModelMixin, - viewsets.ViewSetMixin, - generics.GenericAPIView): - """ - A viewset that provides actions for `create`, `retrieve`, - `update`, `destroy` and `list` actions. - - To use it, override the class and set the `.queryset` - and `.serializer_class` attributes. - """ - pass - -By creating your own base `ViewSet` classes, you can provide common behavior that can be reused in multiple views across your API. - -Note the that `ViewSetMixin` class can also be applied to the standard Django `View` class if you want to use REST framework's automatic routing, but don't want to use it's permissions, authentication and other API policies. - ---- - -# Routers - -Routers provide a convenient and simple shortcut for wiring up your application's URLs. - - router = routers.DefaultRouter() - router.register('^/', APIRoot, 'api-root') - router.register('^users/', UserViewSet, 'user') - router.register('^groups/', GroupViewSet, 'group') - router.register('^accounts/', AccountViewSet, 'account') - - urlpatterns = router.urlpatterns - -[cite]: http://guides.rubyonrails.org/routing.html \ No newline at end of file -- cgit v1.2.3 From c785628300d2b7cce63862a18915c537f8a3ab24 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 4 Apr 2013 20:00:44 +0100 Subject: Fleshing out viewsets/routers --- docs/api-guide/viewsets-routers.md | 50 +++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-guide/viewsets-routers.md b/docs/api-guide/viewsets-routers.md index 817e1b8f..7813c00d 100644 --- a/docs/api-guide/viewsets-routers.md +++ b/docs/api-guide/viewsets-routers.md @@ -48,6 +48,14 @@ If we need to, we can bind this viewset into two seperate views, like so: Typically we wouldn't do this, but would instead register the viewset with a router, and allow the urlconf to be automatically generated. +There are two main advantages of using a `ViewSet` class over using a `View` class. + +* Repeated logic can be combined into a single class. In the above example, we only need to specify the `queryset` once, and it'll be used across multiple views. +* By using routers, we no longer need to deal with wiring up the URL conf ourselves. + +Both of these come with a trade-off. Using regular views and URL confs is more explicit and gives you more control. ViewSets are helpful if you want to get up and running quickly, or when you have a large API and you want to enforce a consistent URL configuration throughout. + + # API Reference ## ViewSet @@ -62,10 +70,50 @@ The `ModelViewSet` class inherits from `GenericAPIView` and includes implementat The actions provided by the `ModelViewSet` class are `.list()`, `.retrieve()`, `.create()`, `.update()`, and `.destroy()`. +#### Example + +Because `ModelViewSet` extends `GenericAPIView`, you'll normally need to provide at least the `queryset` and `serializer_class` attributes. For example: + + class AccountViewSet(viewsets.ModelViewSet): + """ + A simple ViewSet for viewing and editing accounts. + """ + queryset = Account.objects.all() + serializer_class = AccountSerializer + permission_classes = [IsAccountAdminOrReadOnly] + +Note that you can use any of the standard attributes or method overrides provided by `GenericAPIView`. For example, to use a `ViewSet` that dynamically determines the queryset it should operate on, you might do something like this: + + class AccountViewSet(viewsets.ModelViewSet): + """ + A simple ViewSet for viewing and editing the accounts + associated with the user. + """ + serializer_class = AccountSerializer + permission_classes = [IsAccountAdminOrReadOnly] + + def get_queryset(self): + return request.user.accounts.all() + +Also note that although this class provides the complete set of create/list/retrieve/update/destroy actions by default, you can restrict the available operations by using the standard permission classes. + ## ReadOnlyModelViewSet The `ReadOnlyModelViewSet` class also inherits from `GenericAPIView`. As with `ModelViewSet` it also includes implementations for various actions, but unlike `ModelViewSet` only provides the 'read-only' actions, `.list()` and `.retrieve()`. +#### Example + +As with `ModelViewSet`, you'll normally need to provide at least the `queryset` and `serializer_class` attributes. For example: + + class AccountViewSet(viewsets.ReadOnlyModelViewSet): + """ + A simple ViewSet for viewing accounts. + """ + queryset = Account.objects.all() + serializer_class = AccountSerializer + +Again, as with `ModelViewSet`, you can use any of the standard attributes and method overrides available to `GenericAPIView`. + # Custom ViewSet base classes Any standard `View` class can be turned into a `ViewSet` class by mixing in `ViewSetMixin`. You can use this to define your own base classes. @@ -90,7 +138,7 @@ For example, the definition of `ModelViewSet` looks like this: By creating your own base `ViewSet` classes, you can provide common behavior that can be reused in multiple views across your API. -Note the that `ViewSetMixin` class can also be applied to the standard Django `View` class if you want to use REST framework's automatic routing, but don't want to use it's permissions, authentication and other API policies. +For advanced usage, it's worth noting the that `ViewSetMixin` class can also be applied to the standard Django `View` class. Doing so allows you to use REST framework's automatic routing, but don't want to use it's permissions, authentication and other API policies. --- -- cgit v1.2.3 From fb41d2ac8f495ae0728e3f38c6a21306f0507316 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 4 Apr 2013 20:35:40 +0100 Subject: Add support for action and link routing --- docs/tutorial/6-viewsets-and-routers.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md index 9c8a218f..8a2108b3 100644 --- a/docs/tutorial/6-viewsets-and-routers.md +++ b/docs/tutorial/6-viewsets-and-routers.md @@ -12,13 +12,26 @@ Let's take our current set of views, and refactor them into view sets. First of all let's refactor our `UserListView` and `UserDetailView` views into a single `UserViewSet`. We can remove the two views, and replace then with a single class: - class UserViewSet(viewsets.ModelViewSet): + class UserViewSet(viewsets.ReadOnlyModelViewSet): + """ + This viewset automatically provides `list` and `detail` actions. + """ queryset = User.objects.all() serializer_class = UserSerializer Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighlight` view classes. We can remove the three views, and again replace them with a single class. + from rest_framework import viewsets + from rest_framework.decorators import link + class SnippetViewSet(viewsets.ModelViewSet): + """ + This viewset automatically provides `list`, `create`, `retrieve`, + `update` and `destroy` actions. + + Additionally we provide an extra `highlight` action, by using the + `@link` decorator. + """ queryset = Snippet.objects.all() serializer_class = SnippetSerializer permission_classes = (permissions.IsAuthenticatedOrReadOnly, -- cgit v1.2.3 From 371698331c979305b5684f864ee6bf5b6d11a44e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 4 Apr 2013 22:24:30 +0100 Subject: Tweaks --- docs/api-guide/generic-views.md | 4 +-- docs/tutorial/6-viewsets-and-routers.md | 44 ++++++++++++++++++++++----------- 2 files changed, 32 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 20f1be63..caf6f53c 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -208,14 +208,14 @@ Should be mixed in with [SingleObjectAPIView]. Provides a `.update(request, *args, **kwargs)` method, that implements updating and saving an existing model instance. +Also provides a `.partial_update(request, *args, **kwargs)` method, which is similar to the `update` method, except that all fields for the update will be optional. This allows support for HTTP `PATCH` requests. + If an object is updated this returns a `200 OK` response, with a serialized representation of the object as the body of the response. If an object is created, for example when making a `DELETE` request followed by a `PUT` request to the same URL, this returns a `201 Created` response, with a serialized representation of the object as the body of the response. If the request data provided for updating the object was invalid, a `400 Bad Request` response will be returned, with the error details as the body of the response. -A boolean `partial` keyword argument may be supplied to the `.update()` method. If `partial` is set to `True`, all fields for the update will be optional. This allows support for HTTP `PATCH` requests. - Should be mixed in with [SingleObjectAPIView]. ## DestroyModelMixin diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md index 8a2108b3..4c1a1abd 100644 --- a/docs/tutorial/6-viewsets-and-routers.md +++ b/docs/tutorial/6-viewsets-and-routers.md @@ -19,6 +19,8 @@ First of all let's refactor our `UserListView` and `UserDetailView` views into a queryset = User.objects.all() serializer_class = UserSerializer +Here we've used `ReadOnlyModelViewSet` class to automatically provide the default 'read-only' operations. We're still setting the `queryset` and `serializer_class` attributes exactly as we did when we were using regular views, but we no longer need to provide the same information to two seperate classes. + Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighlight` view classes. We can remove the three views, and again replace them with a single class. from rest_framework import viewsets @@ -29,8 +31,7 @@ Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighl This viewset automatically provides `list`, `create`, `retrieve`, `update` and `destroy` actions. - Additionally we provide an extra `highlight` action, by using the - `@link` decorator. + Additionally we also provide an extra `highlight` action. """ queryset = Snippet.objects.all() serializer_class = SnippetSerializer @@ -45,25 +46,40 @@ Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighl def pre_save(self, obj): obj.owner = self.request.user -Notice that we've used the `@link` decorator for the `highlight` method. -This decorator can be used to add custom endpoints, other than the standard `create`/`update`/`delete` endpoints. +This time we've used the `ModelViewSet` class in order to get the complete set of default read and write operations. + +Notice that we've also used the `@link` decorator to create a custom action, named `highlight`. This decorator can be used to add any custom endpoints that don't fit into the standard `create`/`update`/`delete` style. -The `@link` decorator will +Custom actions which use the `@link` decorator will respond to `GET` requests. We could have instead used the `@action` decorator if we wanted an action that responded to `POST` requests. ## Binding ViewSets to URLs explicitly The handler methods only get bound to the actions when we define the URLConf. To see what's going on under the hood let's first explicitly create a set of views from our ViewSets. -In the `urls.py` file we first need to bind our `ViewSet` classes into a set of concrete views. +In the `urls.py` file we bind our `ViewSet` classes into a set of concrete views. from snippets.resources import SnippetResource, UserResource - snippet_list = SnippetViewSet.as_view({'get': 'list', 'post': 'create'}) - snippet_detail = SnippetViewSet.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) - snippet_highlight = SnippetViewSet.as_view({'get': 'highlight'}) - user_list = UserViewSet.as_view({'get': 'list', 'post': 'create'}) - user_detail = UserViewSet.as_view({'get': 'retrieve', 'put': 'update', 'delete': 'destroy'}) + snippet_list = SnippetViewSet.as_view({ + 'get': 'list', + 'post': 'create' + }) + snippet_detail = SnippetViewSet.as_view({ + 'get': 'retrieve', + 'put': 'update', + 'patch': 'partial_update', + 'delete': 'destroy' + }) + snippet_highlight = SnippetViewSet.as_view({ + 'get': 'highlight' + }) + user_list = UserViewSet.as_view({ + 'get': 'list' + }) + user_detail = UserViewSet.as_view({ + 'get': 'retrieve' + }) Notice how we're creating multiple views from each `ViewSet` class, by binding the http methods to the required action for each view. @@ -80,7 +96,7 @@ Now that we've bound our resources into concrete views, that we can register the ## Using Routers -Now that we're using `ViewSet` classes rather than `View` classes, we actually don't need to design the URL conf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using a `Router` class. All we need to do is register the appropriate view sets with a router, and let it do the rest. +Because we're using `ViewSet` classes rather than `View` classes, we actually don't need to design the URL conf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using a `Router` class. All we need to do is register the appropriate view sets with a router, and let it do the rest. Here's our re-wired `urls.py` file. @@ -89,14 +105,14 @@ Here's our re-wired `urls.py` file. # Create a router and register our views and view sets with it. router = DefaultRouter() - router.register(r'^/', views.api_root) + router.register(r'^/$', views.api_root) router.register(r'^snippets/', views.SnippetViewSet, 'snippet') router.register(r'^users/', views.UserViewSet, 'user') # The urlconf is determined automatically by the router. urlpatterns = router.urlpatterns - # Add format suffixes to all our URL patterns. + # We can still add format suffixes to all our URL patterns. urlpatterns = format_suffix_patterns(urlpatterns) ## Trade-offs between views vs viewsets. -- cgit v1.2.3 From 027792c981b1442a018e382a6fa2e58496b0b750 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 9 Apr 2013 11:54:51 +0100 Subject: Viewsets and routers in seperate docs --- docs/api-guide/routers.md | 27 +++++++ docs/api-guide/viewsets-routers.md | 157 ------------------------------------- docs/api-guide/viewsets.md | 145 ++++++++++++++++++++++++++++++++++ docs/index.md | 8 +- docs/template.html | 5 +- 5 files changed, 180 insertions(+), 162 deletions(-) create mode 100644 docs/api-guide/routers.md delete mode 100644 docs/api-guide/viewsets-routers.md create mode 100644 docs/api-guide/viewsets.md (limited to 'docs') diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md new file mode 100644 index 00000000..dbb352fe --- /dev/null +++ b/docs/api-guide/routers.md @@ -0,0 +1,27 @@ + + +# Routers + +> Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your index... a resourceful route declares them in a single line of code. +> +> — [Ruby on Rails Documentation][cite] + +Some Web frameworks such as Rails provide functionality for automatically determining how the URLs for an application should be mapped to the logic that deals with handling incoming requests. + +Conversely, Django stops short of automatically generating URLs, and requires you to explicitly manage your URL configuration. + +REST framework adds support for automatic URL routing, which provides you with a simple, quick and consistent way of wiring your view logic to a set of URLs. + +# API Guide + +Routers provide a convenient and simple shortcut for wiring up your application's URLs. + + router = routers.DefaultRouter() + router.register('^/', APIRoot, 'api-root') + router.register('^users/', UserViewSet, 'user') + router.register('^groups/', GroupViewSet, 'group') + router.register('^accounts/', AccountViewSet, 'account') + + urlpatterns = router.urlpatterns + +[cite]: http://guides.rubyonrails.org/routing.html \ No newline at end of file diff --git a/docs/api-guide/viewsets-routers.md b/docs/api-guide/viewsets-routers.md deleted file mode 100644 index 7813c00d..00000000 --- a/docs/api-guide/viewsets-routers.md +++ /dev/null @@ -1,157 +0,0 @@ - - -# ViewSets & Routers - -> Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your index... a resourceful route declares them in a single line of code. -> -> — [Ruby on Rails Documentation][cite] - -Some Web frameworks such as Rails provide functionality for automatically determining how the URLs for an application should be mapped to the logic that deals with handling incoming requests. - -Conversely, Django stops short of automatically generating URLs, and requires you to explicitly manage your URL configuration. - -REST framework adds support for automatic URL routing, which provides you with a simple, quick and consistent way of wiring your view logic to a set of URLs. - -# ViewSets - -Django REST framework allows you to combine the logic for a set of related views in a single class, called a `ViewSet`. In other frameworks you may also find conceptually similar implementations named something like 'Resources' or 'Controllers'. - -A `ViewSet` class is simply **a type of class-based View, that does not provide any method handlers** such as `.get()` or `.post()`, and instead provides actions such as `.list()` and `.create()`. - -The method handlers for a `ViewSet` are only bound to the corresponding actions at the point of finalizing the view, using the `.as_view()` method. - -Typically, rather than exlicitly registering the views in a viewset in the urlconf, you'll register the viewset with a router class, that automatically determines the urlconf for you. - -## Example - -Let's define a simple viewset that can be used to listing or retrieving all the users in the system. - - class UserViewSet(ViewSet): - """ - A simple ViewSet that for listing or retrieving users. - """ - queryset = User.objects.all() - - def list(self, request): - serializer = UserSerializer(self.queryset, many=True) - return Response(serializer.data) - - def retrieve(self, request, pk=None): - user = get_object_or_404(self.queryset, pk=pk) - serializer = UserSerializer(user) - return Response(serializer.data) - -If we need to, we can bind this viewset into two seperate views, like so: - - user_list = UserViewSet.as_view({'get': 'list'}) - user_detail = UserViewSet.as_view({'get': 'retrieve'}) - -Typically we wouldn't do this, but would instead register the viewset with a router, and allow the urlconf to be automatically generated. - -There are two main advantages of using a `ViewSet` class over using a `View` class. - -* Repeated logic can be combined into a single class. In the above example, we only need to specify the `queryset` once, and it'll be used across multiple views. -* By using routers, we no longer need to deal with wiring up the URL conf ourselves. - -Both of these come with a trade-off. Using regular views and URL confs is more explicit and gives you more control. ViewSets are helpful if you want to get up and running quickly, or when you have a large API and you want to enforce a consistent URL configuration throughout. - - -# API Reference - -## ViewSet - -The `ViewSet` class inherits from `APIView`. You can use any of the standard attributes such as `permission_classes`, `authentication_classes` in order to control the API policy on the viewset. - -The `ViewSet` class does not provide any implementations of actions. In order to use a `ViewSet` class you'll override the class and define the action implementations explicitly. - -## ModelViewSet - -The `ModelViewSet` class inherits from `GenericAPIView` and includes implementations for various actions, by mixing in the behavior of the - -The actions provided by the `ModelViewSet` class are `.list()`, `.retrieve()`, `.create()`, `.update()`, and `.destroy()`. - -#### Example - -Because `ModelViewSet` extends `GenericAPIView`, you'll normally need to provide at least the `queryset` and `serializer_class` attributes. For example: - - class AccountViewSet(viewsets.ModelViewSet): - """ - A simple ViewSet for viewing and editing accounts. - """ - queryset = Account.objects.all() - serializer_class = AccountSerializer - permission_classes = [IsAccountAdminOrReadOnly] - -Note that you can use any of the standard attributes or method overrides provided by `GenericAPIView`. For example, to use a `ViewSet` that dynamically determines the queryset it should operate on, you might do something like this: - - class AccountViewSet(viewsets.ModelViewSet): - """ - A simple ViewSet for viewing and editing the accounts - associated with the user. - """ - serializer_class = AccountSerializer - permission_classes = [IsAccountAdminOrReadOnly] - - def get_queryset(self): - return request.user.accounts.all() - -Also note that although this class provides the complete set of create/list/retrieve/update/destroy actions by default, you can restrict the available operations by using the standard permission classes. - -## ReadOnlyModelViewSet - -The `ReadOnlyModelViewSet` class also inherits from `GenericAPIView`. As with `ModelViewSet` it also includes implementations for various actions, but unlike `ModelViewSet` only provides the 'read-only' actions, `.list()` and `.retrieve()`. - -#### Example - -As with `ModelViewSet`, you'll normally need to provide at least the `queryset` and `serializer_class` attributes. For example: - - class AccountViewSet(viewsets.ReadOnlyModelViewSet): - """ - A simple ViewSet for viewing accounts. - """ - queryset = Account.objects.all() - serializer_class = AccountSerializer - -Again, as with `ModelViewSet`, you can use any of the standard attributes and method overrides available to `GenericAPIView`. - -# Custom ViewSet base classes - -Any standard `View` class can be turned into a `ViewSet` class by mixing in `ViewSetMixin`. You can use this to define your own base classes. - -For example, the definition of `ModelViewSet` looks like this: - - class ModelViewSet(mixins.CreateModelMixin, - mixins.RetrieveModelMixin, - mixins.UpdateModelMixin, - mixins.DestroyModelMixin, - mixins.ListModelMixin, - viewsets.ViewSetMixin, - generics.GenericAPIView): - """ - A viewset that provides actions for `create`, `retrieve`, - `update`, `destroy` and `list` actions. - - To use it, override the class and set the `.queryset` - and `.serializer_class` attributes. - """ - pass - -By creating your own base `ViewSet` classes, you can provide common behavior that can be reused in multiple views across your API. - -For advanced usage, it's worth noting the that `ViewSetMixin` class can also be applied to the standard Django `View` class. Doing so allows you to use REST framework's automatic routing, but don't want to use it's permissions, authentication and other API policies. - ---- - -# Routers - -Routers provide a convenient and simple shortcut for wiring up your application's URLs. - - router = routers.DefaultRouter() - router.register('^/', APIRoot, 'api-root') - router.register('^users/', UserViewSet, 'user') - router.register('^groups/', GroupViewSet, 'group') - router.register('^accounts/', AccountViewSet, 'account') - - urlpatterns = router.urlpatterns - -[cite]: http://guides.rubyonrails.org/routing.html \ No newline at end of file diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md new file mode 100644 index 00000000..83b486dd --- /dev/null +++ b/docs/api-guide/viewsets.md @@ -0,0 +1,145 @@ + + +# ViewSets + +Django REST framework allows you to combine the logic for a set of related views in a single class, called a `ViewSet`. In other frameworks you may also find conceptually similar implementations named something like 'Resources' or 'Controllers'. + +A `ViewSet` class is simply **a type of class-based View, that does not provide any method handlers** such as `.get()` or `.post()`, and instead provides actions such as `.list()` and `.create()`. + +The method handlers for a `ViewSet` are only bound to the corresponding actions at the point of finalizing the view, using the `.as_view()` method. + +Typically, rather than exlicitly registering the views in a viewset in the urlconf, you'll register the viewset with a router class, that automatically determines the urlconf for you. + +## Example + +Let's define a simple viewset that can be used to listing or retrieving all the users in the system. + + class UserViewSet(ViewSet): + """ + A simple ViewSet that for listing or retrieving users. + """ + queryset = User.objects.all() + + def list(self, request): + serializer = UserSerializer(self.queryset, many=True) + return Response(serializer.data) + + def retrieve(self, request, pk=None): + user = get_object_or_404(self.queryset, pk=pk) + serializer = UserSerializer(user) + return Response(serializer.data) + +If we need to, we can bind this viewset into two seperate views, like so: + + user_list = UserViewSet.as_view({'get': 'list'}) + user_detail = UserViewSet.as_view({'get': 'retrieve'}) + +Typically we wouldn't do this, but would instead register the viewset with a router, and allow the urlconf to be automatically generated. + +There are two main advantages of using a `ViewSet` class over using a `View` class. + +* Repeated logic can be combined into a single class. In the above example, we only need to specify the `queryset` once, and it'll be used across multiple views. +* By using routers, we no longer need to deal with wiring up the URL conf ourselves. + +Both of these come with a trade-off. Using regular views and URL confs is more explicit and gives you more control. ViewSets are helpful if you want to get up and running quickly, or when you have a large API and you want to enforce a consistent URL configuration throughout. + + +# API Reference + +## ViewSet + +The `ViewSet` class inherits from `APIView`. You can use any of the standard attributes such as `permission_classes`, `authentication_classes` in order to control the API policy on the viewset. + +The `ViewSet` class does not provide any implementations of actions. In order to use a `ViewSet` class you'll override the class and define the action implementations explicitly. + +## ModelViewSet + +The `ModelViewSet` class inherits from `GenericAPIView` and includes implementations for various actions, by mixing in the behavior of the + +The actions provided by the `ModelViewSet` class are `.list()`, `.retrieve()`, `.create()`, `.update()`, and `.destroy()`. + +#### Example + +Because `ModelViewSet` extends `GenericAPIView`, you'll normally need to provide at least the `queryset` and `serializer_class` attributes. For example: + + class AccountViewSet(viewsets.ModelViewSet): + """ + A simple ViewSet for viewing and editing accounts. + """ + queryset = Account.objects.all() + serializer_class = AccountSerializer + permission_classes = [IsAccountAdminOrReadOnly] + +Note that you can use any of the standard attributes or method overrides provided by `GenericAPIView`. For example, to use a `ViewSet` that dynamically determines the queryset it should operate on, you might do something like this: + + class AccountViewSet(viewsets.ModelViewSet): + """ + A simple ViewSet for viewing and editing the accounts + associated with the user. + """ + serializer_class = AccountSerializer + permission_classes = [IsAccountAdminOrReadOnly] + + def get_queryset(self): + return request.user.accounts.all() + +Also note that although this class provides the complete set of create/list/retrieve/update/destroy actions by default, you can restrict the available operations by using the standard permission classes. + +## ReadOnlyModelViewSet + +The `ReadOnlyModelViewSet` class also inherits from `GenericAPIView`. As with `ModelViewSet` it also includes implementations for various actions, but unlike `ModelViewSet` only provides the 'read-only' actions, `.list()` and `.retrieve()`. + +#### Example + +As with `ModelViewSet`, you'll normally need to provide at least the `queryset` and `serializer_class` attributes. For example: + + class AccountViewSet(viewsets.ReadOnlyModelViewSet): + """ + A simple ViewSet for viewing accounts. + """ + queryset = Account.objects.all() + serializer_class = AccountSerializer + +Again, as with `ModelViewSet`, you can use any of the standard attributes and method overrides available to `GenericAPIView`. + +# Custom ViewSet base classes + +Any standard `View` class can be turned into a `ViewSet` class by mixing in `ViewSetMixin`. You can use this to define your own base classes. + +For example, the definition of `ModelViewSet` looks like this: + + class ModelViewSet(mixins.CreateModelMixin, + mixins.RetrieveModelMixin, + mixins.UpdateModelMixin, + mixins.DestroyModelMixin, + mixins.ListModelMixin, + viewsets.ViewSetMixin, + generics.GenericAPIView): + """ + A viewset that provides actions for `create`, `retrieve`, + `update`, `destroy` and `list` actions. + + To use it, override the class and set the `.queryset` + and `.serializer_class` attributes. + """ + pass + +By creating your own base `ViewSet` classes, you can provide common behavior that can be reused in multiple views across your API. + +For advanced usage, it's worth noting the that `ViewSetMixin` class can also be applied to the standard Django `View` class. Doing so allows you to use REST framework's automatic routing, but don't want to use it's permissions, authentication and other API policies. + +--- + +# Routers + +Routers provide a convenient and simple shortcut for wiring up your application's URLs. + + router = routers.DefaultRouter() + router.register('^/', APIRoot, 'api-root') + router.register('^users/', UserViewSet, 'user') + router.register('^groups/', GroupViewSet, 'group') + router.register('^accounts/', AccountViewSet, 'account') + + urlpatterns = router.urlpatterns + +[cite]: http://guides.rubyonrails.org/routing.html \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 469a5885..d51bbe13 100644 --- a/docs/index.md +++ b/docs/index.md @@ -86,7 +86,7 @@ The tutorial will walk you through the building blocks that make up REST framewo * [3 - Class based views][tut-3] * [4 - Authentication & permissions][tut-4] * [5 - Relationships & hyperlinked APIs][tut-5] -* [6 - ViewSets & Routers][tut-6] +* [6 - Viewsets & routers][tut-6] ## API Guide @@ -96,7 +96,8 @@ The API guide is your complete reference manual to all the functionality provide * [Responses][response] * [Views][views] * [Generic views][generic-views] -* [ViewSets and Routers][viewsets-routers] +* [Viewsets][viewsets] +* [Routers][routers] * [Parsers][parsers] * [Renderers][renderers] * [Serializers][serializers] @@ -205,7 +206,8 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [response]: api-guide/responses.md [views]: api-guide/views.md [generic-views]: api-guide/generic-views.md -[viewsets-routers]: api-guide/viewsets-routers.md +[viewsets]: api-guide/viewsets.md +[routers]: api-guide/routers.md [parsers]: api-guide/parsers.md [renderers]: api-guide/renderers.md [serializers]: api-guide/serializers.md diff --git a/docs/template.html b/docs/template.html index aec3ecc9..931e51c7 100644 --- a/docs/template.html +++ b/docs/template.html @@ -62,7 +62,7 @@
  • 3 - Class based views
  • 4 - Authentication and permissions
  • 5 - Relationships and hyperlinked APIs
    • -
  • 6 - ViewSets and Routers
    • +
  • 6 - Viewsets and routers
  • @@ -72,7 +72,8 @@
  • Responses
  • Views
  • Generic views
    • -
  • ViewSets and Routers
    • +
  • Viewsets
    • +
  • Routers
  • Parsers
  • Renderers
  • Serializers
    • -- cgit v1.2.3 From d75cebf75696602170a9d282d4b114d01d6e5d8e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 11 Apr 2013 15:48:41 +0100 Subject: Remove router bit from viewset docs --- docs/api-guide/viewsets.md | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index 83b486dd..cf6ae33b 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -2,6 +2,11 @@ # ViewSets +> After routing has determined which controller to use for a request, your controller is responsible for making sense of the request and producing the appropriate output. +> +> — [Ruby on Rails Documentation][cite] + + Django REST framework allows you to combine the logic for a set of related views in a single class, called a `ViewSet`. In other frameworks you may also find conceptually similar implementations named something like 'Resources' or 'Controllers'. A `ViewSet` class is simply **a type of class-based View, that does not provide any method handlers** such as `.get()` or `.post()`, and instead provides actions such as `.list()` and `.create()`. @@ -128,18 +133,4 @@ By creating your own base `ViewSet` classes, you can provide common behavior tha For advanced usage, it's worth noting the that `ViewSetMixin` class can also be applied to the standard Django `View` class. Doing so allows you to use REST framework's automatic routing, but don't want to use it's permissions, authentication and other API policies. ---- - -# Routers - -Routers provide a convenient and simple shortcut for wiring up your application's URLs. - - router = routers.DefaultRouter() - router.register('^/', APIRoot, 'api-root') - router.register('^users/', UserViewSet, 'user') - router.register('^groups/', GroupViewSet, 'group') - router.register('^accounts/', AccountViewSet, 'account') - - urlpatterns = router.urlpatterns - [cite]: http://guides.rubyonrails.org/routing.html \ No newline at end of file -- cgit v1.2.3