diff options
Diffstat (limited to 'docs/api-guide/views.md')
| -rw-r--r-- | docs/api-guide/views.md | 110 |
1 files changed, 91 insertions, 19 deletions
diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md index 04647f91..e7f12b45 100644 --- a/docs/api-guide/views.md +++ b/docs/api-guide/views.md @@ -1,4 +1,4 @@ -<a class="github" href="views.py"></a> +<a class="github" href="decorators.py"></a> <a class="github" href="views.py"></a> # Views @@ -6,36 +6,108 @@ > > — [Reinout van Rees][cite] -REST framework provides a simple `APIView` class, built on Django's `django.generics.views.View`. The `APIView` class ensures five main things: +REST framework provides an `APIView` class, which subclasses Django's `View` class. -1. Any requests inside the view will become `Request` instances. -2. `Request` instances will have their `renderers` and `authentication` attributes automatically set. -3. `Response` instances will have their `parsers` and `serializer` attributes automatically set. -4. `APIException` exceptions will be caught and return appropriate responses. -5. Any permissions provided will be checked prior to passing the request to a handler method. +`APIView` classes are different from regular `View` classes in the following ways: -Additionally there are a some minor extras, such as providing a default `options` handler, setting some common headers on the response prior to return, and providing the useful `initial()` and `final()` hooks. +* Requests passed to the handler methods will be REST framework's `Request` instances, not Django's `HttpRequest` instances. +* Handler methods may return REST framework's `Response`, instead of Django's `HttpResponse`. The view will manage content negotiation and setting the correct renderer on the response. +* Any `APIException` exceptions will be caught and mediated into appropriate responses. +* Incoming requests will be authenticated and appropriate permission and/or throttle checks will be run before dispatching the request to the handler method. -## APIView +Using the `APIView` class is pretty much the same as using a regular `View` class, as usual, the incoming request is dispatched to an appropriate handler method such as `.get()` or `.post()`. Additionally, a number of attributes may be set on the class that control various aspects of the API policy. -## Method handlers +For example: -Describe that APIView handles regular .get(), .post(), .put(), .delete() etc... + class ListUsers(APIView): + """ + View to list all users in the system. + + * Requires token authentication. + * Only admin users are able to access this view. + """ + authentication_classes = (authentication.TokenAuthentication,) + permission_classes = (permissions.IsAdmin,) -## .initial(request, *args, **kwargs) + def get(self, request, format=None): + """ + Return a list of all users. + """ + users = [user.username for user in User.objects.all()] + return Response(users) -## .final(request, response, *args, **kwargs) +## API policy attributes -## .parsers +The following attributes control the pluggable aspects of API views. -## .renderers +### .renderer_classes -## .serializer +### .parser_classes -## .authentication +### .authentication_classes -## .permissions +### .throttle_classes -## .headers +### .permission_classes + +### .content_negotiation_class + +## API policy instantiation methods + +The following methods are used by REST framework to instantiate the various pluggable API policies. You won't typically need to override these methods. + +### .get_renderers(self) + +### .get_parsers(self) + +### .get_authenticators(self) + +### .get_throttles(self) + +### .get_permissions(self) + +### .get_content_negotiator(self) + +## API policy implementation methods + +The following methods are called before dispatching to the handler method. + +### .check_permissions(...) + +### .check_throttles(...) + +### .perform_content_negotiation(...) + +## Dispatch methods + +The following methods are called directly by the view's `.dispatch()` method. +These perform any actions that need to occur before or after calling the handler methods such as `.get()`, `.post()`, `put()` and `.delete()`. + +### .initial(self, request, *args, **kwargs) + +Performs any actions that need to occur before the handler method gets called. +This method is used to enforce permissions and throttling, and perform content negotiation. + +You won't typically need to override this method. + +### .handle_exception(self, exc) + +Any exception thrown by the handler method will be passed to this method, which either returns a `Response` instance, or re-raises the exception. + +The default implementation handles any subclass of `rest_framework.exceptions.APIException`, as well as Django's `Http404` and `PermissionDenied` exceptions, and returns an appropriate error response. + +If you need to customize the error responses your API returns you should subclass this method. + +### .initialize_request(self, request, *args, **kwargs) + +Ensures that the request object that is passed to the handler method is an instance of `Request`, rather than the usual Django `HttpRequest`. + +You won't typically need to override this method. + +### .finalize_response(self, request, response, *args, **kwargs) + +Ensures that any `Response` object returned from the handler method will be rendered into the correct content type, as determined by the content negotation. + +You won't typically need to override this method. [cite]: http://reinout.vanrees.org/weblog/2011/08/24/class-based-views-usage.html
\ No newline at end of file |