From b907a4448572e3c48137e983248fb7411246563a Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 18 Nov 2013 15:50:29 +0000 Subject: [PATCH] Remove .html suffixes --- api-guide/authentication.html | 89 ++++----- api-guide/content-negotiation.html | 85 ++++----- api-guide/exceptions.html | 89 ++++----- api-guide/fields.html | 85 ++++----- api-guide/filtering.html | 85 ++++----- api-guide/format-suffixes.html | 85 ++++----- api-guide/generic-views.html | 85 ++++----- api-guide/pagination.html | 85 ++++----- api-guide/parsers.html | 85 ++++----- api-guide/permissions.html | 91 +++++----- api-guide/relations.html | 87 ++++----- api-guide/renderers.html | 91 +++++----- api-guide/requests.html | 99 +++++----- api-guide/responses.html | 87 ++++----- api-guide/reverse.html | 85 ++++----- api-guide/routers.html | 85 ++++----- api-guide/serializers.html | 87 ++++----- api-guide/settings.html | 85 ++++----- api-guide/status-codes.html | 85 ++++----- api-guide/testing.html | 85 ++++----- api-guide/throttling.html | 87 ++++----- api-guide/views.html | 89 ++++----- api-guide/viewsets.html | 85 ++++----- index.html | 169 +++++++++--------- topics/2.2-announcement.html | 85 ++++----- topics/2.3-announcement.html | 89 ++++----- topics/ajax-csrf-cors.html | 85 ++++----- topics/browsable-api.html | 87 ++++----- topics/browser-enhancements.html | 85 ++++----- topics/contributing.html | 85 ++++----- topics/credits.html | 83 ++++----- topics/documenting-your-api.html | 87 ++++----- topics/release-notes.html | 91 +++++----- topics/rest-framework-2-announcement.html | 87 ++++----- topics/rest-hypermedia-hateoas.html | 87 ++++----- topics/writable-nested-serializers.html | 81 ++++----- tutorial/1-serialization.html | 89 ++++----- tutorial/2-requests-and-responses.html | 91 +++++----- tutorial/3-class-based-views.html | 87 ++++----- .../4-authentication-and-permissions.html | 94 +++++----- .../5-relationships-and-hyperlinked-apis.html | 87 ++++----- tutorial/6-viewsets-and-routers.html | 85 ++++----- tutorial/quickstart.html | 87 ++++----- 43 files changed, 1934 insertions(+), 1888 deletions(-) diff --git a/api-guide/authentication.html b/api-guide/authentication.html index c28b2239b..63c2f3f01 100644 --- a/api-guide/authentication.html +++ b/api-guide/authentication.html @@ -4,6 +4,7 @@ Django REST framework - Authentication + @@ -41,8 +42,8 @@
GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -220,14 +221,14 @@

    Auth needs to be pluggable.

    — Jacob Kaplan-Moss, "REST worst practices"

    -

    Authentication is the mechanism of associating an incoming request with a set of identifying credentials, such as the user the request came from, or the token that it was signed with. The permission and throttling policies can then use those credentials to determine if the request should be permitted.

    +

    Authentication is the mechanism of associating an incoming request with a set of identifying credentials, such as the user the request came from, or the token that it was signed with. The permission and throttling policies can then use those credentials to determine if the request should be permitted.

    REST framework provides a number of authentication schemes out of the box, and also allows you to implement custom schemes.

    Authentication is always run at the very start of the view, before the permission and throttling checks occur, and before any other code is allowed to proceed.

    The request.user property will typically be set to an instance of the contrib.auth package's User class.

    The request.auth property is used for any additional authentication information, for example, it may be used to represent an authentication token that the request was signed with.

    Note: Don't forget that authentication by itself won't allow or disallow an incoming request, it simply identifies the credentials that the request was made with.

    -

    For information on how to setup the permission polices for your API please see the permissions documentation.

    +

    For information on how to setup the permission polices for your API please see the permissions documentation.

    How authentication is determined

    The authentication schemes are always defined as a list of classes. REST framework will attempt to authenticate with each class in the list, and will set request.user and request.auth using the return value of the first class that successfully authenticates.

    diff --git a/api-guide/content-negotiation.html b/api-guide/content-negotiation.html index e7f3e693c..c21a6430e 100644 --- a/api-guide/content-negotiation.html +++ b/api-guide/content-negotiation.html @@ -4,6 +4,7 @@ Django REST framework - Content negotiation + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/exceptions.html b/api-guide/exceptions.html index 3a7a8311f..16dc8752b 100644 --- a/api-guide/exceptions.html +++ b/api-guide/exceptions.html @@ -4,6 +4,7 @@ Django REST framework - Exceptions + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -284,11 +285,11 @@ def custom_exception_handler(exc):

    AuthenticationFailed

    Signature: AuthenticationFailed(detail=None)

    Raised when an incoming request includes incorrect authentication.

    -

    By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See the authentication documentation for more details.

    +

    By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See the authentication documentation for more details.

    NotAuthenticated

    Signature: NotAuthenticated(detail=None)

    Raised when an unauthenticated request fails the permission checks.

    -

    By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See the authentication documentation for more details.

    +

    By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See the authentication documentation for more details.

    PermissionDenied

    Signature: PermissionDenied(detail=None)

    Raised when an authenticated request fails the permission checks.

    diff --git a/api-guide/fields.html b/api-guide/fields.html index 90581f27d..dae3cc692 100644 --- a/api-guide/fields.html +++ b/api-guide/fields.html @@ -4,6 +4,7 @@ Django REST framework - Serializer fields + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/filtering.html b/api-guide/filtering.html index 7cb8fdebe..28dae4e86 100644 --- a/api-guide/filtering.html +++ b/api-guide/filtering.html @@ -4,6 +4,7 @@ Django REST framework - Filtering + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/format-suffixes.html b/api-guide/format-suffixes.html index 3abdb6742..38557dafd 100644 --- a/api-guide/format-suffixes.html +++ b/api-guide/format-suffixes.html @@ -4,6 +4,7 @@ Django REST framework - Format suffixes + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/generic-views.html b/api-guide/generic-views.html index ccf85552a..e1ef2ea9c 100644 --- a/api-guide/generic-views.html +++ b/api-guide/generic-views.html @@ -4,6 +4,7 @@ Django REST framework - Generic views + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/pagination.html b/api-guide/pagination.html index 7c05df0f8..395a94ec8 100644 --- a/api-guide/pagination.html +++ b/api-guide/pagination.html @@ -4,6 +4,7 @@ Django REST framework - Pagination + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/parsers.html b/api-guide/parsers.html index 6c38f7169..5a4fcd7cf 100644 --- a/api-guide/parsers.html +++ b/api-guide/parsers.html @@ -4,6 +4,7 @@ Django REST framework - Parsers + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/permissions.html b/api-guide/permissions.html index 7a0886b9a..7153f0c2a 100644 --- a/api-guide/permissions.html +++ b/api-guide/permissions.html @@ -4,6 +4,7 @@ Django REST framework - Permissions + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -220,7 +221,7 @@

    Authentication or identification by itself is not usually sufficient to gain access to information or code. For that, the entity requesting access must have authorization.

    — Apple Developer Documentation

    -

    Together with authentication and throttling, permissions determine whether a request should be granted or denied access.

    +

    Together with authentication and throttling, permissions determine whether a request should be granted or denied access.

    Permission checks are always run at the very start of the view, before any other code is allowed to proceed. Permission checks will typically use the authentication information in the request.user and request.auth properties to determine if the incoming request should be permitted.

    How permissions are determined

    Permissions in REST framework are always defined as a list of permission classes.

    @@ -338,7 +339,7 @@ else:

    Note: In versions 2.0 and 2.1, the signature for the permission checks always included an optional obj parameter, like so: .has_permission(self, request, view, obj=None). The method would be called twice, first for the global permission checks, with no object supplied, and second for the object-level check when required.

    As of version 2.2 this signature has now been replaced with two separate method calls, which is more explicit and obvious. The old style signature continues to work, but its use will result in a PendingDeprecationWarning, which is silent by default. In 2.3 this will be escalated to a DeprecationWarning, and in 2.4 the old-style signature will be removed.

    -

    For more details see the 2.2 release announcement.

    +

    For more details see the 2.2 release announcement.

    Examples

    The following is an example of a permission class that checks the incoming request's IP address against a blacklist, and denies the request if the IP has been blacklisted.

    @@ -371,7 +372,7 @@ class BlacklistPermission(permissions.BasePermission): return obj.owner == request.user

    Note that the generic views will check the appropriate object level permissions, but if you're writing your own custom views, you'll need to make sure you check the object level permission checks yourself. You can do so by calling self.check_object_permissions(request, obj) from the view once you have the object instance. This call will raise an appropriate APIException if any object-level permission checks fail, and will otherwise simply return.

    -

    Also note that the generic views will only check the object-level permissions for views that retrieve a single model instance. If you require object-level filtering of list views, you'll need to filter the queryset separately. See the filtering documentation for more details.

    +

    Also note that the generic views will only check the object-level permissions for views that retrieve a single model instance. If you require object-level filtering of list views, you'll need to filter the queryset separately. See the filtering documentation for more details.

    Third party packages

    The following third party packages are also available.

    diff --git a/api-guide/relations.html b/api-guide/relations.html index 33805a02b..d4bdc3931 100644 --- a/api-guide/relations.html +++ b/api-guide/relations.html @@ -4,6 +4,7 @@ Django REST framework - Serializer relations + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -575,7 +576,7 @@ They continue to function, but their usage will raise a PendingDeprecation

    The null=<bool> flag has been deprecated in favor of the required=<bool> flag. It will continue to function, but will raise a PendingDeprecationWarning.

    In the 2.3 release, these warnings will be escalated to a DeprecationWarning, which is loud by default. In the 2.4 release, these parts of the API will be removed entirely.

    -

    For more details see the 2.2 release announcement.

    +

    For more details see the 2.2 release announcement.

    diff --git a/api-guide/renderers.html b/api-guide/renderers.html index 8077c8044..11b0e1613 100644 --- a/api-guide/renderers.html +++ b/api-guide/renderers.html @@ -4,6 +4,7 @@ Django REST framework - Renderers + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -234,7 +235,7 @@

    How the renderer is determined

    The set of valid renderers for a view is always defined as a list of classes. When a view is entered REST framework will perform content negotiation on the incoming request, and determine the most appropriate renderer to satisfy the request.

    The basic process of content negotiation involves examining the request's Accept header, to determine which media types it expects in the response. Optionally, format suffixes on the URL may be used to explicitly request a particular representation. For example the URL http://example.com/api/users_count.json might be an endpoint that always returns JSON data.

    -

    For more information see the documentation on content negotiation.

    +

    For more information see the documentation on content negotiation.

    Setting the renderers

    The default set of renderers may be set globally, using the DEFAULT_RENDERER_CLASSES setting. For example, the following settings would use YAML as the main media type and also include the self describing API.

    REST_FRAMEWORK = {
@@ -309,7 +310,7 @@ def user_count_view(request, format=None):
 
    JSONPRenderer
    
 
    Renders the request data into JSONP.  The JSONP media type provides a mechanism of allowing cross-domain AJAX requests, by wrapping a JSON response in a javascript callback.
    
 
    The javascript callback function must be set by the client including a callback URL query parameter.  For example http://example.com/api/users?callback=jsonpCallback.  If the callback function is not explicitly set by the client it will default to 'callback'.
    
-
    Note: If you require cross-domain AJAX requests, you may want to consider using the more modern approach of CORS as an alternative to JSONP.  See the CORS documentation for more details.
    
+
    Note: If you require cross-domain AJAX requests, you may want to consider using the more modern approach of CORS as an alternative to JSONP.  See the CORS documentation for more details.
    
 
    .media_type: application/javascript
    
 
    .format: '.jsonp'
    
 
    .charset: utf-8
    
@@ -388,7 +389,7 @@ def simple_html_view(request):
         return JSONRenderer()

    MultiPartRenderer

    -

    This renderer is used for rendering HTML multipart form data. It is not suitable as a response renderer, but is instead used for creating test requests, using REST framework's test client and test request factory.

    +

    This renderer is used for rendering HTML multipart form data. It is not suitable as a response renderer, but is instead used for creating test requests, using REST framework's test client and test request factory.

    .media_type: multipart/form-data; boundary=BoUnDaRyStRiNg

    .format: '.multipart'

    .charset: utf-8

    diff --git a/api-guide/requests.html b/api-guide/requests.html index 6e8abc374..ee15a0a8a 100644 --- a/api-guide/requests.html +++ b/api-guide/requests.html @@ -4,6 +4,7 @@ Django REST framework - Requests + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -228,10 +229,10 @@
  • It supports parsing the content of HTTP methods other than POST, meaning that you can access the content of PUT and PATCH requests.
  • It supports REST framework's flexible request parsing, rather than just supporting form data. For example you can handle incoming JSON data in the same way that you handle incoming form data.
    • -

    For more details see the parsers documentation.

    +

    For more details see the parsers documentation.

    .FILES

    request.FILES returns any uploaded files that may be present in the content of the request body. This is the same as the standard HttpRequest behavior, except that the same flexible request parsing is used for request.DATA.

    -

    For more details see the parsers documentation.

    +

    For more details see the parsers documentation.

    .QUERY_PARAMS

    request.QUERY_PARAMS is a more correctly named synonym for request.GET.

    For clarity inside your code, we recommend using request.QUERY_PARAMS instead of the usual request.GET, as any HTTP method type may include query parameters.

    @@ -252,11 +253,11 @@

    .user

    request.user typically returns an instance of django.contrib.auth.models.User, although the behavior depends on the authentication policy being used.

    If the request is unauthenticated the default value of request.user is an instance of django.contrib.auth.models.AnonymousUser.

    -

    For more details see the authentication documentation.

    +

    For more details see the authentication documentation.

    .auth

    request.auth returns any additional authentication context. The exact behavior of request.auth depends on the authentication policy being used, but it may typically be an instance of the token that the request was authenticated against.

    If the request is unauthenticated, or if no additional context is present, the default value of request.auth is None.

    -

    For more details see the authentication documentation.

    +

    For more details see the authentication documentation.

    .authenticators

    The APIView class or @api_view decorator will ensure that this property is automatically set to a list of Authentication instances, based on the authentication_classes set on the view or based on the DEFAULT_AUTHENTICATORS setting.

    You won't typically need to access this property.

    @@ -266,17 +267,17 @@

    .method

    request.method returns the uppercased string representation of the request's HTTP method.

    Browser-based PUT, PATCH and DELETE forms are transparently supported.

    -

    For more information see the browser enhancements documentation.

    +

    For more information see the browser enhancements documentation.

    .content_type

    request.content_type, returns a string object representing the media type of the HTTP request's body, or an empty string if no media type was provided.

    You won't typically need to directly access the request's content type, as you'll normally rely on REST framework's default request parsing behavior.

    If you do need to access the content type of the request you should use the .content_type property in preference to using request.META.get('HTTP_CONTENT_TYPE'), as it provides transparent support for browser-based non-form content.

    -

    For more information see the browser enhancements documentation.

    +

    For more information see the browser enhancements documentation.

    .stream

    request.stream returns a stream representing the content of the request body.

    You won't typically need to directly access the request's content, as you'll normally rely on REST framework's default request parsing behavior.

    If you do need to access the raw content directly, you should use the .stream property in preference to using request.content, as it provides transparent support for browser-based non-form content.

    -

    For more information see the browser enhancements documentation.

    +

    For more information see the browser enhancements documentation.

    Standard HttpRequest attributes

    As REST framework's Request extends Django's HttpRequest, all the other standard attributes and methods are also available. For example the request.META and request.session dictionaries are available as normal.

    diff --git a/api-guide/responses.html b/api-guide/responses.html index 749d68f08..9c4707401 100644 --- a/api-guide/responses.html +++ b/api-guide/responses.html @@ -4,6 +4,7 @@ Django REST framework - Responses + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -230,7 +231,7 @@

    Arguments:

    diff --git a/api-guide/routers.html b/api-guide/routers.html index 4654a8f0f..e3d212da5 100644 --- a/api-guide/routers.html +++ b/api-guide/routers.html @@ -4,6 +4,7 @@ Django REST framework - Routers + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/serializers.html b/api-guide/serializers.html index 96340bcb9..39ca749c6 100644 --- a/api-guide/serializers.html +++ b/api-guide/serializers.html @@ -4,6 +4,7 @@ Django REST framework - Serializers + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -524,7 +525,7 @@ The ModelSerializer class lets you automatically create a Serialize

    Relational fields

    When serializing model instances, there are a number of different ways you might choose to represent relationships. The default representation for ModelSerializer is to use the primary keys of the related instances.

    Alternative representations include serializing using hyperlinks, serializing complete nested representations, or serializing with a custom representation.

    -

    For full details see the serializer relations documentation.

    +

    For full details see the serializer relations documentation.

    HyperlinkedModelSerializer

    The HyperlinkedModelSerializer class is similar to the ModelSerializer class except that it uses hyperlinks to represent relationships, rather than primary keys.

    diff --git a/api-guide/settings.html b/api-guide/settings.html index 1308c0843..0ab1f6758 100644 --- a/api-guide/settings.html +++ b/api-guide/settings.html @@ -4,6 +4,7 @@ Django REST framework - Settings + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/status-codes.html b/api-guide/status-codes.html index c806bde54..c6a3dea89 100644 --- a/api-guide/status-codes.html +++ b/api-guide/status-codes.html @@ -4,6 +4,7 @@ Django REST framework - Status Codes + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/testing.html b/api-guide/testing.html index a289e2bde..7f90df040 100644 --- a/api-guide/testing.html +++ b/api-guide/testing.html @@ -4,6 +4,7 @@ Django REST framework - Testing + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/api-guide/throttling.html b/api-guide/throttling.html index 5358b0a9f..7f8539f09 100644 --- a/api-guide/throttling.html +++ b/api-guide/throttling.html @@ -4,6 +4,7 @@ Django REST framework - Throttling + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -213,7 +214,7 @@

    HTTP/1.1 420 Enhance Your Calm

    Twitter API rate limiting response

    -

    Throttling is similar to permissions, in that it determines if a request should be authorized. Throttles indicate a temporary state, and are used to control the rate of requests that clients can make to an API.

    +

    Throttling is similar to permissions, in that it determines if a request should be authorized. Throttles indicate a temporary state, and are used to control the rate of requests that clients can make to an API.

    As with permissions, multiple throttles may be used. Your API might have a restrictive throttle for unauthenticated requests, and a less restrictive throttle for authenticated requests.

    Another scenario where you might want to use multiple throttles would be if you need to impose different constraints on different parts of the API, due to some services being particularly resource-intensive.

    Multiple throttles can also be used if you want to impose both burst throttling rates, and sustained throttling rates. For example, you might want to limit a user to a maximum of 60 requests per minute, and 1000 requests per day.

    diff --git a/api-guide/views.html b/api-guide/views.html index 11684c477..21c4ce4e1 100644 --- a/api-guide/views.html +++ b/api-guide/views.html @@ -4,6 +4,7 @@ Django REST framework - Class Based Views + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -296,9 +297,9 @@ This method is used to enforce permissions and throttling, and perform content n def hello_world(request): return Response({"message": "Hello, world!"}) -

    This view will use the default renderers, parsers, authentication classes etc specified in the settings.

    +

    This view will use the default renderers, parsers, authentication classes etc specified in the settings.

    API policy decorators

    -

    To override the default settings, REST framework provides a set of additional decorators which can be added to your views. These must come after (below) the @api_view decorator. For example, to create a view that uses a throttle to ensure it can only be called once per day by a particular user, use the @throttle_classes decorator, passing a list of throttle classes:

    +

    To override the default settings, REST framework provides a set of additional decorators which can be added to your views. These must come after (below) the @api_view decorator. For example, to create a view that uses a throttle to ensure it can only be called once per day by a particular user, use the @throttle_classes decorator, passing a list of throttle classes:

    from rest_framework.decorators import api_view, throttle_classes
 from rest_framework.throttling import UserRateThrottle
 
diff --git a/api-guide/viewsets.html b/api-guide/viewsets.html
index 72cf2b23a..a9952205a 100644
--- a/api-guide/viewsets.html
+++ b/api-guide/viewsets.html
@@ -4,6 +4,7 @@
     
     Django REST framework - ViewSets
     
+    
     
     
     
@@ -41,8 +42,8 @@
       
    
         
    
             GitHub
-            Next 
-             Previous
+            Next 
+             Previous
              Search
           
             
@@ -56,56 +57,56 @@
               
  • 
                 Tutorial 
                 
               
    • 
               
  • 
                 API Guide 
                 
               
    • 
               
  • 
                 Topics 
                 
               
    • 
             
diff --git a/index.html b/index.html
index af272a2da..7582f4f8d 100644
--- a/index.html
+++ b/index.html
@@ -4,6 +4,7 @@
     
     Django REST framework - APIs made easy
     
+    
     
     
     
@@ -41,7 +42,7 @@
       
    
         
    
             GitHub
-            Next 
+            Next 
              Previous
              Search
           
@@ -56,56 +57,56 @@
               
  • 
                 Tutorial 
                 
               
    • 
               
  • 
                 API Guide 
                 
               
    • 
               
  • 
                 Topics 
                 
               
    • 
             
@@ -224,9 +225,9 @@
 
    Some reasons you might want to use REST framework:
    
 
 
    There is a live example API for testing purposes, available here.
    
@@ -317,57 +318,57 @@ urlpatterns = patterns('',
 )

    Quickstart

    -

    Can't wait to get started? The quickstart guide is the fastest way to get up and running, and building APIs with REST framework.

    +

    Can't wait to get started? The quickstart guide is the fastest way to get up and running, and building APIs with REST framework.

    Tutorial

    The tutorial will walk you through the building blocks that make up REST framework. It'll take a little while to get through, but it'll give you a comprehensive understanding of how everything fits together, and is highly recommended reading.

    API Guide

    The API guide is your complete reference manual to all the functionality provided by REST framework.

    Topics

    General guides to using REST framework.

    Development

    If you want to work on REST framework itself, clone the repository, then...

    diff --git a/topics/2.2-announcement.html b/topics/2.2-announcement.html index fbd04e29c..431177bc9 100644 --- a/topics/2.2-announcement.html +++ b/topics/2.2-announcement.html @@ -4,6 +4,7 @@ Django REST framework - REST framework 2.2 announcement + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/topics/2.3-announcement.html b/topics/2.3-announcement.html index 82c2f8d0a..3ac50d6d5 100644 --- a/topics/2.3-announcement.html +++ b/topics/2.3-announcement.html @@ -4,6 +4,7 @@ Django REST framework - REST framework 2.3 announcement + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -217,7 +218,7 @@

    REST framework 2.3 announcement

    REST framework 2.3 makes it even quicker and easier to build your Web APIs.

    ViewSets and Routers

    -

    The 2.3 release introduces the ViewSet and Router classes.

    +

    The 2.3 release introduces the ViewSet and Router classes.

    A viewset is simply a type of class based view that allows you to group multiple views into a single common class.

    Routers allow you to automatically determine the URLconf for your viewset classes.

    As an example of just how simple REST framework APIs can now be, here's an API written in a single urls.py module:

    @@ -250,7 +251,7 @@ urlpatterns = patterns('', url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework')) ) -

    The best place to get started with ViewSets and Routers is to take a look at the newest section in the tutorial, which demonstrates their usage.

    +

    The best place to get started with ViewSets and Routers is to take a look at the newest section in the tutorial, which demonstrates their usage.

    Simpler views

    This release rationalises the API and implementation of the generic views, dropping the dependency on Django's SingleObjectMixin and MultipleObjectMixin classes, removing a number of unneeded attributes, and generally making the implementation more obvious and easy to work with.

    This improvement is reflected in improved documentation for the GenericAPIView base class, and should make it easier to determine how to override methods on the base class if you need to write customized subclasses.

    diff --git a/topics/ajax-csrf-cors.html b/topics/ajax-csrf-cors.html index 47a73333d..0c90d60cb 100644 --- a/topics/ajax-csrf-cors.html +++ b/topics/ajax-csrf-cors.html @@ -4,6 +4,7 @@ Django REST framework - Working with AJAX, CSRF & CORS + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/topics/browsable-api.html b/topics/browsable-api.html index 88165d490..f85235117 100644 --- a/topics/browsable-api.html +++ b/topics/browsable-api.html @@ -4,6 +4,7 @@ Django REST framework - The Browsable API + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -208,7 +209,7 @@

    API may stand for Application Programming Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the HTML format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using POST, PUT, and DELETE.

    URLs

    -

    If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The rest_framework package includes a reverse helper for this purpose.

    +

    If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The rest_framework package includes a reverse helper for this purpose.

    Formats

    By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using ?format= in the request, so you can look at the raw JSON response in a browser by adding ?format=json to the URL. There are helpful extensions for viewing JSON in Firefox and Chrome.

    Customizing

    diff --git a/topics/browser-enhancements.html b/topics/browser-enhancements.html index 7f71b9320..118d290cb 100644 --- a/topics/browser-enhancements.html +++ b/topics/browser-enhancements.html @@ -4,6 +4,7 @@ Django REST framework - Browser enhancements + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/topics/contributing.html b/topics/contributing.html index 4c96c60c8..7170c91d5 100644 --- a/topics/contributing.html +++ b/topics/contributing.html @@ -4,6 +4,7 @@ Django REST framework - Contributing to REST framework + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/topics/credits.html b/topics/credits.html index 03f0ba76f..f0086c58c 100644 --- a/topics/credits.html +++ b/topics/credits.html @@ -4,6 +4,7 @@ Django REST framework - Credits + @@ -42,7 +43,7 @@
    GitHub Next - Previous + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/topics/documenting-your-api.html b/topics/documenting-your-api.html index 79bba0d6e..b622c0edb 100644 --- a/topics/documenting-your-api.html +++ b/topics/documenting-your-api.html @@ -4,6 +4,7 @@ Django REST framework - Documenting your API + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -261,7 +262,7 @@

    The hypermedia approach

    To be fully RESTful an API should present its available actions as hypermedia controls in the responses that it sends.

    In this approach, rather than documenting the available API endpoints up front, the description instead concentrates on the media types that are used. The available actions take may be taken on any given URL are not strictly fixed, but are instead made available by the presence of link and form controls in the returned document.

    -

    To implement a hypermedia API you'll need to decide on an appropriate media type for the API, and implement a custom renderer and parser for that media type. The REST, Hypermedia & HATEOAS section of the documentation includes pointers to background reading, as well as links to various hypermedia formats.

    +

    To implement a hypermedia API you'll need to decide on an appropriate media type for the API, and implement a custom renderer and parser for that media type. The REST, Hypermedia & HATEOAS section of the documentation includes pointers to background reading, as well as links to various hypermedia formats.

    diff --git a/topics/release-notes.html b/topics/release-notes.html index 5d4322b2b..f7ae55a24 100644 --- a/topics/release-notes.html +++ b/topics/release-notes.html @@ -4,6 +4,7 @@ Django REST framework - Release Notes + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -356,7 +357,7 @@
  • Made Login template easier to restyle.
  • Bugfix: Fix issue with depth>1 on ModelSerializer.
    • -

    Note: See the 2.3 announcement for full details.

    +

    Note: See the 2.3 announcement for full details.

    2.2.x series

    2.2.7

    @@ -441,7 +442,7 @@
  • Bugfix: Fix issue with deserializing empty to-many relations.
  • Bugfix: Ensure model field validation is still applied for ModelSerializer subclasses with an custom .restore_object() method.
    • -

    Note: See the 2.2 announcement for full details.

    +

    Note: See the 2.2 announcement for full details.

    2.1.x series

    2.1.17

    @@ -611,7 +612,7 @@

    Date: 30th Oct 2012

    0.4.x series

    diff --git a/topics/rest-framework-2-announcement.html b/topics/rest-framework-2-announcement.html index 99a0604bd..4cf7f9800 100644 --- a/topics/rest-framework-2-announcement.html +++ b/topics/rest-framework-2-announcement.html @@ -4,6 +4,7 @@ Django REST framework - Django REST framework 2 + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -256,7 +257,7 @@

    We're really pleased with how the docs style looks - it's simple and clean, is easy to navigate around, and we think it reads great.

    Summary

    In short, we've engineered the hell outta this thing, and we're incredibly proud of the result.

    -

    If you're interested please take a browse around the documentation. The tutorial is a great place to get started.

    +

    If you're interested please take a browse around the documentation. The tutorial is a great place to get started.

    There's also a live sandbox version of the tutorial API available for testing.

    diff --git a/topics/rest-hypermedia-hateoas.html b/topics/rest-hypermedia-hateoas.html index 2f26f901e..899e3b868 100644 --- a/topics/rest-hypermedia-hateoas.html +++ b/topics/rest-hypermedia-hateoas.html @@ -4,6 +4,7 @@ Django REST framework - REST, Hypermedia & HATEOAS + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -223,7 +224,7 @@ the Design of Network-based Software Architectures.

    REST framework is an agnostic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style.

    What REST framework provides.

    It is self evident that REST framework makes it possible to build Hypermedia APIs. The browsable API that it offers is built on HTML - the hypermedia language of the web.

    -

    REST framework also includes serialization and parser/renderer components that make it easy to build appropriate media types, hyperlinked relations for building well-connected systems, and great support for content negotiation.

    +

    REST framework also includes serialization and parser/renderer components that make it easy to build appropriate media types, hyperlinked relations for building well-connected systems, and great support for content negotiation.

    What REST framework doesn't provide.

    What REST framework doesn't do is give you is machine readable hypermedia formats such as HAL, Collection+JSON, JSON API or HTML microformats by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope.

    diff --git a/topics/writable-nested-serializers.html b/topics/writable-nested-serializers.html index 0ccdc25b8..b7d535cad 100644 --- a/topics/writable-nested-serializers.html +++ b/topics/writable-nested-serializers.html @@ -4,6 +4,7 @@ Django REST framework - Writable nested serializers + @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/tutorial/1-serialization.html b/tutorial/1-serialization.html index 47bb95044..8028f27ab 100644 --- a/tutorial/1-serialization.html +++ b/tutorial/1-serialization.html @@ -4,6 +4,7 @@ Django REST framework - Tutorial 1: Serialization + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -211,7 +212,7 @@

    Tutorial 1: Serialization

    Introduction

    This tutorial will cover creating a simple pastebin code highlighting Web API. Along the way it will introduce the various components that make up REST framework, and give you a comprehensive understanding of how everything fits together.

    -

    The tutorial is fairly in-depth, so you should probably get a cookie and a cup of your favorite brew before getting started. If you just want a quick overview, you should head over to the quickstart documentation instead.

    +

    The tutorial is fairly in-depth, so you should probably get a cookie and a cup of your favorite brew before getting started. If you just want a quick overview, you should head over to the quickstart documentation instead.

    Note: The code for this tutorial is available in the tomchristie/rest-framework-tutorial repository on GitHub. The completed implementation is also online as a sandbox version for testing, available here.

    @@ -498,7 +499,7 @@ Quit the server with CONTROL-C.

    Where are we now

    We're doing okay so far, we've got a serialization API that feels pretty similar to Django's Forms API, and some regular Django views.

    Our API views don't do anything particularly special at the moment, beyond serving json responses, and there are some error handling edge cases we'd still like to clean up, but it's a functioning Web API.

    -

    We'll see how we can start to improve things in part 2 of the tutorial.

    +

    We'll see how we can start to improve things in part 2 of the tutorial.

    diff --git a/tutorial/2-requests-and-responses.html b/tutorial/2-requests-and-responses.html index af045a354..fe084a554 100644 --- a/tutorial/2-requests-and-responses.html +++ b/tutorial/2-requests-and-responses.html @@ -4,6 +4,7 @@ Django REST framework - Tutorial 2: Requests and Responses + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -307,7 +308,7 @@ urlpatterns = format_suffix_patterns(urlpatterns)

    We don't necessarily need to add these extra url patterns in, but it gives us a simple, clean way of referring to a specific format.

    How's it looking?

    -

    Go ahead and test the API from the command line, as we did in tutorial part 1. Everything is working pretty similarly, although we've got some nicer error handling if we send invalid requests.

    +

    Go ahead and test the API from the command line, as we did in tutorial part 1. Everything is working pretty similarly, although we've got some nicer error handling if we send invalid requests.

    We can get a list of all of the snippets, as before.

    curl http://127.0.0.1:8000/snippets/
 
@@ -336,9 +337,9 @@ curl -X POST http://127.0.0.1:8000/snippets/ -d '{"code": "print 456"}' -H "Cont
 
    Browsability
    
 
    Because the API chooses the content type of the response based on the client request, it will, by default, return an HTML-formatted representation of the resource when that resource is requested by a web browser.  This allows for the API to return a fully web-browsable HTML representation.
    
 
    Having a web-browsable API is a huge usability win, and makes developing and using your API much easier.  It also dramatically lowers the barrier-to-entry for other developers wanting to inspect and work with your API.
    
-
    See the browsable api topic for more information about the browsable API feature and how to customize it.
    
+
    See the browsable api topic for more information about the browsable API feature and how to customize it.
    
 
    What's next?
    
-
    In tutorial part 3, we'll start using class based views, and see how generic views reduce the amount of code we need to write.
    
+
    In tutorial part 3, we'll start using class based views, and see how generic views reduce the amount of code we need to write.
    diff --git a/tutorial/3-class-based-views.html b/tutorial/3-class-based-views.html index 886916795..d4a14f113 100644 --- a/tutorial/3-class-based-views.html +++ b/tutorial/3-class-based-views.html @@ -4,6 +4,7 @@ Django REST framework - Tutorial 3: Class Based Views + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -329,7 +330,7 @@ class SnippetDetail(generics.RetrieveUpdateDestroyAPIView): serializer_class = SnippetSerializer

    Wow, that's pretty concise. We've gotten a huge amount for free, and our code looks like good, clean, idiomatic Django.

    -

    Next we'll move onto part 4 of the tutorial, where we'll take a look at how we can deal with authentication and permissions for our API.

    +

    Next we'll move onto part 4 of the tutorial, where we'll take a look at how we can deal with authentication and permissions for our API.

    diff --git a/tutorial/4-authentication-and-permissions.html b/tutorial/4-authentication-and-permissions.html index 5ce9c1491..bde22d77d 100644 --- a/tutorial/4-authentication-and-permissions.html +++ b/tutorial/4-authentication-and-permissions.html @@ -4,6 +4,7 @@ Django REST framework - Tutorial 4: Authentication & Permissions + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -263,7 +264,10 @@ class UserSerializer(serializers.ModelSerializer):

    Because 'snippets' is a reverse relationship on the User model, it will not be included by default when using the ModelSerializer class, so we needed to add an explicit field for it.

    We'll also add a couple of views to views.py. We'd like to just use read-only views for the user representations, so we'll use the ListAPIView and RetrieveAPIView generic class based views.

    -
    class UserList(generics.ListAPIView):
+
    from django.contrib.auth.models import User
+
+
+class UserList(generics.ListAPIView):
     queryset = User.objects.all()
     serializer_class = UserSerializer
 
@@ -347,7 +351,7 @@ class IsOwnerOrReadOnly(permissions.BasePermission):
 
    
 
    Now, if you open a browser again, you find that the 'DELETE' and 'PUT' actions only appear on a snippet instance endpoint if you're logged in as the same user that created the code snippet.
    
 
    Authenticating with the API
    
-
    Because we now have a set of permissions on the API, we need to authenticate our requests to it if we want to edit any snippets.  We haven't set up any authentication classes, so the defaults are currently applied, which are SessionAuthentication and BasicAuthentication.
    
+
    Because we now have a set of permissions on the API, we need to authenticate our requests to it if we want to edit any snippets.  We haven't set up any authentication classes, so the defaults are currently applied, which are SessionAuthentication and BasicAuthentication.
    
 
    When we interact with the API through the web browser, we can login, and the browser session will then provide the required authentication for the requests.
    
 
    If we're interacting with the API programmatically we need to explicitly provide the authentication credentials on each request.
    
 
    If we try to create a snippet without authenticating, we'll get an error:
    
@@ -362,7 +366,7 @@ class IsOwnerOrReadOnly(permissions.BasePermission):

    Summary

    We've now got a fairly fine-grained set of permissions on our Web API, and end points for users of the system and for the code snippets that they have created.

    -

    In part 5 of the tutorial we'll look at how we can tie everything together by creating an HTML endpoint for our highlighted snippets, and improve the cohesion of our API by using hyperlinking for the relationships within the system.

    +

    In part 5 of the tutorial we'll look at how we can tie everything together by creating an HTML endpoint for our highlighted snippets, and improve the cohesion of our API by using hyperlinking for the relationships within the system.

    diff --git a/tutorial/5-relationships-and-hyperlinked-apis.html b/tutorial/5-relationships-and-hyperlinked-apis.html index a55f37d28..68bf60f7c 100644 --- a/tutorial/5-relationships-and-hyperlinked-apis.html +++ b/tutorial/5-relationships-and-hyperlinked-apis.html @@ -4,6 +4,7 @@ Django REST framework - Tutorial 5: Relationships & Hyperlinked APIs + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -331,7 +332,7 @@ urlpatterns += patterns('',

    Browsing the API

    If we open a browser and navigate to the browsable API, you'll find that you can now work your way around the API simply by following links.

    You'll also be able to see the 'highlight' links on the snippet instances, that will take you to the highlighted code HTML representations.

    -

    In part 6 of the tutorial we'll look at how we can use ViewSets and Routers to reduce the amount of code we need to build our API.

    +

    In part 6 of the tutorial we'll look at how we can use ViewSets and Routers to reduce the amount of code we need to build our API.

    diff --git a/tutorial/6-viewsets-and-routers.html b/tutorial/6-viewsets-and-routers.html index 353a8b627..6dd440291 100644 --- a/tutorial/6-viewsets-and-routers.html +++ b/tutorial/6-viewsets-and-routers.html @@ -4,6 +4,7 @@ Django REST framework - Tutorial 6: ViewSets & Routers + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • diff --git a/tutorial/quickstart.html b/tutorial/quickstart.html index 079177cef..89ec57f0e 100644 --- a/tutorial/quickstart.html +++ b/tutorial/quickstart.html @@ -4,6 +4,7 @@ Django REST framework - Quickstart + @@ -41,8 +42,8 @@
    GitHub - Next - Previous + Next + Previous Search @@ -56,56 +57,56 @@
  • Tutorial
  • API Guide
  • Topics
    • @@ -344,7 +345,7 @@ REST_FRAMEWORK = {

    Or directly through the browser...

    Quick start image

    Great, that was easy!

    -

    If you want to get a more in depth understanding of how REST framework fits together head on over to the tutorial, or start browsing the API guide.

    +

    If you want to get a more in depth understanding of how REST framework fits together head on over to the tutorial, or start browsing the API guide.