From 20cf4f71cce2821e9a6d0af76973f65c5d7e504f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 27 Sep 2012 16:28:13 +0100 Subject: [PATCH] Latest docs build --- api-guide/parsers.html | 20 +++++++- api-guide/renderers.html | 20 +++++++- api-guide/requests.html | 2 +- api-guide/views.html | 102 +++++++++++++++++++++++++++------------ topics/contributing.html | 10 +++- topics/credits.html | 2 + 6 files changed, 118 insertions(+), 38 deletions(-) diff --git a/api-guide/parsers.html b/api-guide/parsers.html index 08d5bf8da..4c2eb7594 100644 --- a/api-guide/parsers.html +++ b/api-guide/parsers.html @@ -94,7 +94,12 @@
@@ -103,7 +108,18 @@

parsers.py

Parsers

-

.parse(request)

+
+

Machine interacting web services tend to use more +structured formats for sending data than form-encoded, since they're +sending more complex data than simple forms

+

— Malcom Tredinnick, Django developers group

+
+

JSONParser

+

YAMLParser

+

XMLParser

+

FormParser

+

MultiPartParser

+

Custom parsers

diff --git a/api-guide/renderers.html b/api-guide/renderers.html index 7a1347f4d..651e23992 100644 --- a/api-guide/renderers.html +++ b/api-guide/renderers.html @@ -94,7 +94,13 @@
@@ -103,7 +109,17 @@

renderers.py

Renderers

-

.render(response)

+
+

Before a TemplateResponse instance can be returned to the client, it must be rendered. The rendering process takes the intermediate representation of template and context, and turns it into the final byte stream that can be served to the client.

+

— Django documentation

+
+

JSONRenderer

+

JSONPRenderer

+

YAMLRenderer

+

XMLRenderer

+

DocumentingHTMLRenderer

+

TemplatedHTMLRenderer

+

Custom renderers

diff --git a/api-guide/requests.html b/api-guide/requests.html index bfe7acbd6..3fae1f673 100644 --- a/api-guide/requests.html +++ b/api-guide/requests.html @@ -113,7 +113,7 @@

Requests

If you're doing REST-based web service stuff ... you should ignore request.POST.

-

— Malcom Tredinnick, Django developers group

+

— Malcom Tredinnick, Django developers group

REST framework's Request class extends the standard HttpRequest, adding support for parsing multiple content types, allowing browser-based PUT, DELETE and other methods, and adding flexible per-request authentication.

.method

diff --git a/api-guide/views.html b/api-guide/views.html index e33d08501..dea62322b 100644 --- a/api-guide/views.html +++ b/api-guide/views.html @@ -94,48 +94,88 @@
-

views.py

+

decorators.py views.py

Views

Django's class based views are a welcome departure from the old-style views.

— Reinout van Rees

-

REST framework provides a simple APIView class, built on Django's django.generics.views.View. The APIView class ensures five main things:

-
    -
  1. Any requests inside the view will become Request instances.
    2. -
  2. Request instances will have their renderers and authentication attributes automatically set.
    3. -
  3. Response instances will have their parsers and serializer attributes automatically set.
    4. -
  4. APIException exceptions will be caught and return appropriate responses.
    5. -
  5. Any permissions provided will be checked prior to passing the request to a handler method.
    6. -
-

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.

-

APIView

-

Method handlers

-

Describe that APIView handles regular .get(), .post(), .put(), .delete() etc...

-

.initial(request, args, *kwargs)

-

.final(request, response, args, *kwargs)

-

.parsers

-

.renderers

-

.serializer

-

.authentication

-

.permissions

-

.headers

+

REST framework provides an APIView class, which subclasses Django's View class.

+

APIView classes are different from regular View classes in the following ways:

+ +

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.

+

For example:

+
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,)
+
+    def get(self, request, format=None):
+        """
+        Return a list of all users.
+        """
+        users = [user.username for user in User.objects.all()]
+        return Response(users)
+
+

API policy attributes

+

The following attributes control the pluggable aspects of API views.

+

.renderer_classes

+

.parser_classes

+

.authentication_classes

+

.throttle_classes

+

.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.

diff --git a/topics/contributing.html b/topics/contributing.html index 7ebde9a22..9479f52bc 100644 --- a/topics/contributing.html +++ b/topics/contributing.html @@ -94,8 +94,9 @@
@@ -103,9 +104,14 @@

Contributing to REST framework

+
+

The world can only really be changed one piece at a time. The art is picking that piece.

+

— Tim Berners-Lee

+
+

Running the tests

+

Building the docs

Managing compatibility issues

Describe compat module

-

Running the tests

diff --git a/topics/credits.html b/topics/credits.html index c89081c5b..33c741192 100644 --- a/topics/credits.html +++ b/topics/credits.html @@ -144,6 +144,8 @@
  • Shawn Lewis - shawnlewis
  • Alec Perkins - alecperkins
  • Michael Barrett - phobologic
    • +
  • Mathieu Dhondt - laundromat
    • +
  • Johan Charpentier - cyberj

    • Many thanks to everyone who's contributed to the project.

    Additional thanks