From 1d65378886990a1dc5c36403d454ce251fbda457 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 9 Mar 2015 10:18:32 +0000 Subject: [PATCH] Update documentation --- api-guide/fields/index.html | 5 +---- api-guide/generic-views/index.html | 5 +---- api-guide/metadata/index.html | 5 +---- api-guide/pagination/index.html | 16 ++++++++-------- api-guide/relations/index.html | 5 +---- api-guide/requests/index.html | 5 +---- api-guide/serializers/index.html | 5 +---- api-guide/validators/index.html | 9 +++------ index.html | 4 ++-- 9 files changed, 19 insertions(+), 40 deletions(-) diff --git a/api-guide/fields/index.html b/api-guide/fields/index.html index 1b7019fe0..eb1e4fc62 100644 --- a/api-guide/fields/index.html +++ b/api-guide/fields/index.html @@ -576,10 +576,7 @@ -
-

Note: This is the documentation for the version 3.0 of REST framework. Documentation for version 2.4 is also available.

-
-

Serializer fields

+

Serializer fields

Each field in a Form class is responsible not only for validating data, but also for "cleaning" it — normalizing it to a consistent format.

— Django documentation

diff --git a/api-guide/generic-views/index.html b/api-guide/generic-views/index.html index 288a71158..098dc7758 100644 --- a/api-guide/generic-views/index.html +++ b/api-guide/generic-views/index.html @@ -496,10 +496,7 @@ -
-

Note: This is the documentation for the version 3.0 of REST framework. Documentation for version 2.4 is also available.

-
-

Generic views

+

Generic views

Django’s generic views... were developed as a shortcut for common usage patterns... They take certain common idioms and patterns found in view development and abstract them so that you can quickly write common views of data without having to repeat yourself.

— Django Documentation

diff --git a/api-guide/metadata/index.html b/api-guide/metadata/index.html index 9d30200e4..6bba18af6 100644 --- a/api-guide/metadata/index.html +++ b/api-guide/metadata/index.html @@ -388,10 +388,7 @@ -
-

Note: This is the documentation for the version 3.0 of REST framework. Documentation for version 2.4 is also available.

-
-

Metadata

+

Metadata

[The OPTIONS] method allows a client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.

— RFC7231, Section 4.3.7.

diff --git a/api-guide/pagination/index.html b/api-guide/pagination/index.html index 37cb383ed..d9a3395a5 100644 --- a/api-guide/pagination/index.html +++ b/api-guide/pagination/index.html @@ -502,10 +502,10 @@ class StandardResultsSetPagination(PageNumberPagination): }

Setup

-

To enable the PageNumberPagination style globally, use the following configuration, modifying the DEFAULT_PAGE_SIZE as desired:

+

To enable the PageNumberPagination style globally, use the following configuration, modifying the PAGE_SIZE as desired:

REST_FRAMEWORK = {
     'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
-    'DEFAULT_PAGE_SIZE': 100
+    'PAGE_SIZE': 100
 }

On GenericAPIView subclasses you may also set the pagination_class attribute to select PageNumberPagination on a per-view basis.

@@ -513,7 +513,7 @@ class StandardResultsSetPagination(PageNumberPagination):

The PageNumberPagination class includes a number of attributes that may be overridden to modify the pagination style.

To set these attributes you should override the PageNumberPagination class, and then enable your custom pagination class as above.

    -
  • page_size - A numeric value indicating the page size. If set, this overrides the DEFAULT_PAGE_SIZE setting. Defaults to the same value as the DEFAULT_PAGE_SIZE settings key.
    • +
  • page_size - A numeric value indicating the page size. If set, this overrides the PAGE_SIZE setting. Defaults to the same value as the PAGE_SIZE settings key.
  • page_query_param - A string value indicating the name of the query parameter to use for the pagination control.
  • page_size_query_param - If set, this is a string value indicating the name of a query parameter that allows the client to set the page size on a per-request basis. Defaults to None, indicating that the client may not control the requested page size.
  • max_page_size - If set, this is a numeric value indicating the maximum allowable requested page size. This attribute is only valid if page_size_query_param is also set.
    • @@ -544,13 +544,13 @@ class StandardResultsSetPagination(PageNumberPagination): 'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination' } -

    Optionally, you may also set a DEFAULT_PAGE_SIZE key. If the DEFAULT_PAGE_SIZE parameter is also used then the limit query parameter will be optional, and may be omitted by the client.

    +

    Optionally, you may also set a PAGE_SIZE key. If the PAGE_SIZE parameter is also used then the limit query parameter will be optional, and may be omitted by the client.

    On GenericAPIView subclasses you may also set the pagination_class attribute to select LimitOffsetPagination on a per-view basis.

    Configuration

    The LimitOffsetPagination class includes a number of attributes that may be overridden to modify the pagination style.

    To set these attributes you should override the LimitOffsetPagination class, and then enable your custom pagination class as above.

      -
    • default_limit - A numeric value indicating the limit to use if one is not provided by the client in a query parameter. Defaults to the same value as the DEFAULT_PAGE_SIZE settings key.
      • +
    • default_limit - A numeric value indicating the limit to use if one is not provided by the client in a query parameter. Defaults to the same value as the PAGE_SIZE settings key.
    • limit_query_param - A string value indicating the name of the "limit" query parameter. Defaults to 'limit'.
    • offset_query_param - A string value indicating the name of the "offset" query parameter. Defaults to 'offset'.
    • max_limit - If set this is a numeric value indicating the maximum allowable limit that may be requested by the client. Defaults to None.
      • @@ -566,7 +566,7 @@ class StandardResultsSetPagination(PageNumberPagination):
    • Supports usage with very large datasets. With extremely large datasets pagination using offset-based pagination styles may become inefficient or unusable. Cursor based pagination schemes instead have fixed-time properties, and do not slow down as the dataset size increases.

    Details and limitations

    -

    Proper use of cursor based pagination a little attention to detail. You'll need to think about what ordering you want the scheme to be applied against. The default is to order by "-created". This assumes that there must be a 'created' timestamp field on the model instances, and will present a "timeline" style paginated view, with the most recently added items first.

    +

    Proper use of cursor based pagination requires a little attention to detail. You'll need to think about what ordering you want the scheme to be applied against. The default is to order by "-created". This assumes that there must be a 'created' timestamp field on the model instances, and will present a "timeline" style paginated view, with the most recently added items first.

    You can modify the ordering by overriding the 'ordering' attribute on the pagination class, or by using the OrderingFilter filter class together with CursorPagination. When used with OrderingFilter you should strongly consider restricting the fields that the user may order by.

    Proper usage of cursor pagination should have an ordering field that satisfies the following:

      @@ -578,10 +578,10 @@ class StandardResultsSetPagination(PageNumberPagination):

      Using an ordering field that does not satisfy these constraints will generally still work, but you'll be loosing some of the benefits of cursor pagination.

      For more technical details on the implementation we use for cursor pagination, the "Building cursors for the Disqus API" blog post gives a good overview of the basic approach.

      Setup

      -

      To enable the CursorPagination style globally, use the following configuration, modifying the DEFAULT_PAGE_SIZE as desired:

      +

      To enable the CursorPagination style globally, use the following configuration, modifying the PAGE_SIZE as desired:

      REST_FRAMEWORK = {
     'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.CursorPagination',
-    'DEFAULT_PAGE_SIZE': 100
+    'PAGE_SIZE': 100
 }

      On GenericAPIView subclasses you may also set the pagination_class attribute to select CursorPagination on a per-view basis.

      diff --git a/api-guide/relations/index.html b/api-guide/relations/index.html index 67ecbb4f9..57512cd1a 100644 --- a/api-guide/relations/index.html +++ b/api-guide/relations/index.html @@ -464,10 +464,7 @@ -
      -

      Note: This is the documentation for the version 3.0 of REST framework. Documentation for version 2.4 is also available.

      -
      -

      Serializer relations

      +

      Serializer relations

      Bad programmers worry about the code. Good programmers worry about data structures and their relationships.

      diff --git a/api-guide/requests/index.html b/api-guide/requests/index.html index 3db6d3805..c3bb7fc7d 100644 --- a/api-guide/requests/index.html +++ b/api-guide/requests/index.html @@ -460,10 +460,7 @@ -
      -

      Note: This is the documentation for the version 3.0 of REST framework. Documentation for version 2.4 is also available.

      -
      -

      Requests

      +

      Requests

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

      — Malcom Tredinnick, Django developers group

      diff --git a/api-guide/serializers/index.html b/api-guide/serializers/index.html index b5b732137..88d033272 100644 --- a/api-guide/serializers/index.html +++ b/api-guide/serializers/index.html @@ -552,10 +552,7 @@ -
      -

      Note: This is the documentation for the version 3.0 of REST framework. Documentation for version 2.4 is also available.

      -
      -

      Serializers

      +

      Serializers

      Expanding the usefulness of the serializers is something that we would like to address. However, it's not a trivial problem, and it diff --git a/api-guide/validators/index.html b/api-guide/validators/index.html index 395fd9de1..d97fc213e 100644 --- a/api-guide/validators/index.html +++ b/api-guide/validators/index.html @@ -424,10 +424,7 @@ -

      -

      Note: This is the documentation for the version 3.0 of REST framework. Documentation for version 2.4 is also available.

      -
      -

      Validators

      +

      Validators

      Validators can be useful for re-using validation logic between different types of fields.

      — Django documentation

      @@ -446,7 +443,7 @@

      Example

      As an example of how REST framework uses explicit validation, we'll take a simple model class that has a field with a uniqueness constraint.

      class CustomerReportRecord(models.Model):
-    time_raised = models.DateTimeField(default=timezone.now, editable=False) 
+    time_raised = models.DateTimeField(default=timezone.now, editable=False)
     reference = models.CharField(unique=True, max_length=20)
     description = models.TextField()
      @@ -455,7 +452,7 @@ class Meta: model = CustomerReportRecord -

      If we open up the Django shell using manage.py shell we can now

      +

      If we open up the Django shell using manage.py shell we can now

      >>> from project.example.serializers import CustomerReportSerializer
 >>> serializer = CustomerReportSerializer()
 >>> print(repr(serializer))
diff --git a/index.html b/index.html
index 35d311040..5d9b02d93 100644
--- a/index.html
+++ b/index.html
@@ -461,8 +461,8 @@
 
      
 
 
      
-
      Note: This is the documentation for the version 3.0 of REST framework. Documentation for version 2.4 is also available.
      
-
      For more details see the 3.0 release notes.
      
+
      Note: This is the documentation for the version 3.1 of REST framework. Documentation for version 2.4 is also available.
      
+
      For more details see the 3.1 release notes.