From 5967f15f7f5c87987ab60e4b7dc682b06f3ab511 Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Wed, 14 Nov 2012 16:11:35 +0100 Subject: updated docs --- docs/api-guide/generic-views.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 360ef1a2..9e5119cb 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -147,6 +147,10 @@ Provides a `.list(request, *args, **kwargs)` method, that implements listing a q Should be mixed in with [MultipleObjectAPIView]. +**Arguments**: + +* `page_size` - Hook to adjust page_size per request. + ## CreateModelMixin Provides a `.create(request, *args, **kwargs)` method, that implements creating and saving a new model instance. -- cgit v1.2.3 From 1e83b60a43c26db921d6910092362feb3a76500d Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Wed, 14 Nov 2012 18:00:59 +0100 Subject: added description how to use the auth token --- docs/api-guide/authentication.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 3137b9d4..cb1e2645 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -97,6 +97,21 @@ If successfully authenticated, `TokenAuthentication` provides the following cred **Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. +If you want every user to have an automatically generated Token, you can simply catch the User's `post_save` signal. + + @receiver(post_save, sender=User) + def create_auth_token(sender, instance=None, created=False, **kwargs): + if created: + Token.objects.create(user=instance) + +If you've already created some User`'s, you can run a script like this. + + from django.contrib.auth.models import User + from rest_framework.authtoken.models import Token + + for user in User.objects.all(): + Token.objects.get_or_create(user=user) + ## OAuthAuthentication This policy uses the [OAuth 2.0][oauth] protocol to authenticate requests. OAuth is appropriate for server-server setups, such as when you want to allow a third-party service to access your API on a user's behalf. -- cgit v1.2.3 From eb20b5663e68ce01453eeb855922874001f42d0f Mon Sep 17 00:00:00 2001 From: Rob Romano Date: Tue, 13 Nov 2012 15:03:42 -0800 Subject: Added documentation on how to use the token authentication login view. --- docs/api-guide/authentication.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index cb1e2645..a55059a8 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -112,6 +112,21 @@ If you've already created some User`'s, you can run a script like this. for user in User.objects.all(): Token.objects.get_or_create(user=user) +When using TokenAuthentication, it may be useful to add a login view for clients to retrieve the token. + +REST framework provides a built-in login view. To use it, add a pattern to include the token login view for clients as follows: + + urlpatterns += patterns('', + url(r'^api-token-auth/', include('rest_framework.authtoken.urls', + namespace='rest_framework')) + ) + +The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The only restriction is that the included urls must use the `'rest_framework'` namespace. + +The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: + + { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } + ## OAuthAuthentication This policy uses the [OAuth 2.0][oauth] protocol to authenticate requests. OAuth is appropriate for server-server setups, such as when you want to allow a third-party service to access your API on a user's behalf. -- cgit v1.2.3 From 321ba156ca45da8a4b3328c4aec6a9235f32e5f8 Mon Sep 17 00:00:00 2001 From: Rob Romano Date: Tue, 13 Nov 2012 16:49:13 -0800 Subject: Renamed AuthTokenView to ObtainAuthToken, added obtain_auth_token var, updated tests & docs. Left authtoken.urls in place as example. --- docs/api-guide/authentication.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index a55059a8..a30bd22c 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -114,18 +114,15 @@ If you've already created some User`'s, you can run a script like this. When using TokenAuthentication, it may be useful to add a login view for clients to retrieve the token. -REST framework provides a built-in login view. To use it, add a pattern to include the token login view for clients as follows: +REST framework provides a built-in login view for clients to retrieve the token called `rest_framework.authtoken.obtain_auth_token`. To use it, add a pattern to include the token login view for clients as follows: urlpatterns += patterns('', - url(r'^api-token-auth/', include('rest_framework.authtoken.urls', - namespace='rest_framework')) + url(r'^api-token-auth/', 'rest_framework.authtoken.obtain_auth_token') ) -The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The only restriction is that the included urls must use the `'rest_framework'` namespace. +The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: -The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: - - { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } + { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } ## OAuthAuthentication -- cgit v1.2.3 From 38e94bb8b4e04249b18b9b57ef2ddcb7cfc4efa4 Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Thu, 15 Nov 2012 11:15:05 +0100 Subject: added global and per resource on/off switch + updated docs --- docs/api-guide/generic-views.md | 3 ++- docs/api-guide/settings.md | 6 ++++++ 2 files changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 9e5119cb..734a91e9 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -149,7 +149,8 @@ Should be mixed in with [MultipleObjectAPIView]. **Arguments**: -* `page_size` - Hook to adjust page_size per request. +* `allow_page_size_param` - Allows you to overwrite the global settings `ALLOW_PAGE_SIZE_PARAM` for a specific view. +* `page_size_param` - Allows you to customize the page_size parameter. Default is `page_size`. ## CreateModelMixin diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 4f87b30d..2f90369b 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -150,4 +150,10 @@ Default: `'accept'` Default: `'format'` +## ALLOW_PAGE_SIZE_PARAM + +Allows you to globally pass a page size parameter for an individual request. + +Default: `'True'` + [cite]: http://www.python.org/dev/peps/pep-0020/ -- cgit v1.2.3 From 3ae203a0184d27318a8a828ce322b151ade0340f Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Thu, 15 Nov 2012 12:06:43 +0100 Subject: updated script to just use page_size_kwarg --- docs/api-guide/generic-views.md | 3 +-- docs/api-guide/settings.md | 8 ++++++-- 2 files changed, 7 insertions(+), 4 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 734a91e9..3346c70a 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -149,8 +149,7 @@ Should be mixed in with [MultipleObjectAPIView]. **Arguments**: -* `allow_page_size_param` - Allows you to overwrite the global settings `ALLOW_PAGE_SIZE_PARAM` for a specific view. -* `page_size_param` - Allows you to customize the page_size parameter. Default is `page_size`. +* `page_size_kwarg` - Allows you to overwrite the global settings `PAGE_SIZE_KWARG` for a specific view. You can also turn it off for a specific view by setting it to `None`. Default is `page_size`. ## CreateModelMixin diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 2f90369b..8fce9e4e 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -150,10 +150,14 @@ Default: `'accept'` Default: `'format'` -## ALLOW_PAGE_SIZE_PARAM +## PAGE_SIZE_KWARG Allows you to globally pass a page size parameter for an individual request. -Default: `'True'` +The name of the GET parameter of views which inherit ListModelMixin for requesting data with an individual page size. + +If the value if this setting is `None` the passing a page size is turned off by default. + +Default: `'page_size'` [cite]: http://www.python.org/dev/peps/pep-0020/ -- cgit v1.2.3 From b4cfb46a56c8f7d9bc4340d5443f3a2d57ba9b58 Mon Sep 17 00:00:00 2001 From: Marko Tibold Date: Fri, 16 Nov 2012 00:22:08 +0100 Subject: WIP on docs for File- and ImageFileds. --- docs/api-guide/fields.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 0485b158..0b25a6ef 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -165,6 +165,38 @@ A floating point representation. Corresponds to `django.db.models.fields.FloatField`. +## FileField + +A file representation. Performs Django's standard FileField validation. + +Corresponds to `django.forms.fields.FileField`. + +### Optional arguments + +#### `max_length` + +Maximum length for the file name. This value is obtained from the model when used with a ModelSerializer. + +Defaults to `None`, meaning validation is skipped. + +#### `allow_empty_file` + +Determines if empty file uploads are allowed. + +Defaults to `False` + +## ImageField + +An image representation. + +Corresponds to `django.forms.fields.ImageField`. + +### Optional arguments + +Same as FileField. + +Requires the `PIL` package. + --- # Relational Fields -- cgit v1.2.3 From c5765641a44ad2fb3b80f63f9a47e0dd7f432c94 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 17:28:08 +0000 Subject: Fix typo --- docs/api-guide/filtering.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index 14ab9a26..95d9d526 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -71,7 +71,7 @@ We can override `.get_queryset()` to deal with URLs such as `http://example.com/ by filtering against a `username` query parameter in the URL. """ queryset = Purchase.objects.all() - username = self.request.QUERY_PARAMS.get('username', None): + username = self.request.QUERY_PARAMS.get('username', None) if username is not None: queryset = queryset.filter(purchaser__username=username) return queryset -- cgit v1.2.3 From 2f2bde69e42825ad55318e5a5745ee9655b3f81b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 20:58:49 +0000 Subject: Docs, tox and travis use django-filter 0.5.4 --- docs/api-guide/filtering.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/filtering.md b/docs/api-guide/filtering.md index 95d9d526..53ea7cbc 100644 --- a/docs/api-guide/filtering.md +++ b/docs/api-guide/filtering.md @@ -84,9 +84,9 @@ As well as being able to override the default queryset, REST framework also incl REST framework supports pluggable backends to implement filtering, and provides an implementation which uses the [django-filter] package. -To use REST framework's default filtering backend, first install `django-filter`. +To use REST framework's filtering backend, first install `django-filter`. - pip install -e git+https://github.com/alex/django-filter.git#egg=django-filter + pip install django-filter You must also set the filter backend to `DjangoFilterBackend` in your settings: @@ -94,7 +94,6 @@ You must also set the filter backend to `DjangoFilterBackend` in your settings: 'FILTER_BACKEND': 'rest_framework.filters.DjangoFilterBackend' } -**Note**: The currently supported version of `django-filter` is the `master` branch. A PyPI release is expected to be coming soon. ## Specifying filter fields -- cgit v1.2.3 From 0076e2f462402dbb7bd7b3a446d2c397e6bf8d81 Mon Sep 17 00:00:00 2001 From: Marko Tibold Date: Fri, 16 Nov 2012 23:23:34 +0100 Subject: Added brief docs for URLField and SlugField. --- docs/api-guide/fields.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 0485b158..5977cae2 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -131,6 +131,18 @@ or `django.db.models.fields.TextField`. **Signature:** `CharField(max_length=None, min_length=None)` +## URLField + +Corresponds to `django.db.models.fields.URLField`. Uses Django's `django.core.validators.URLValidator` for validation. + +**Signature:** `CharField(max_length=200, min_length=None)` + +## SlugField + +Corresponds to `django.db.models.fields.SlugField`. + +**Signature:** `CharField(max_length=50, min_length=None)` + ## ChoiceField A field that can accept a value out of a limited set of choices. -- cgit v1.2.3 From f801e5d3050591403de04fde7d18522fabc8fe49 Mon Sep 17 00:00:00 2001 From: Marko Tibold Date: Fri, 16 Nov 2012 23:44:55 +0100 Subject: Simplified docs a bit for FileField and ImageField. Added note about MultipartParser only supporting file uploads and Django's default upload handlers. --- docs/api-guide/fields.md | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 0b25a6ef..7f42dc5e 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -171,19 +171,11 @@ A file representation. Performs Django's standard FileField validation. Corresponds to `django.forms.fields.FileField`. -### Optional arguments +**Signature:** `FileField(max_length=None, allow_empty_file=False)` -#### `max_length` - -Maximum length for the file name. This value is obtained from the model when used with a ModelSerializer. - -Defaults to `None`, meaning validation is skipped. - -#### `allow_empty_file` - -Determines if empty file uploads are allowed. - -Defaults to `False` + - `max_length` designates the maximum length for the file name. + + - `allow_empty_file` designates if empty files are allowed. ## ImageField @@ -191,11 +183,14 @@ An image representation. Corresponds to `django.forms.fields.ImageField`. -### Optional arguments +Requires the `PIL` package. -Same as FileField. +Signature and validation is the same as with `FileField`. -Requires the `PIL` package. +--- + +**Note:** `FileFields` and `ImageFields` are only suitable for use with MultiPartParser, since eg json doesn't support file uploads. +Django's regular [FILE_UPLOAD_HANDLERS] are used for handling uploaded files. --- @@ -318,3 +313,4 @@ This field is always read-only. * `slug_url_kwarg` - The named url parameter for the slug field lookup. Default is to use the same value as given for `slug_field`. [cite]: http://www.python.org/dev/peps/pep-0020/ +[FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS -- cgit v1.2.3 From 31f01bd6315f46bf28bb4c9c25a5298785fc4fc6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 22:45:57 +0000 Subject: Polishing to page size query parameters & more docs --- docs/api-guide/generic-views.md | 22 ++++++++++++++++++---- docs/api-guide/settings.md | 26 ++++++++++++++++---------- 2 files changed, 34 insertions(+), 14 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 3346c70a..33ec89d2 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -123,18 +123,36 @@ Each of the generic views provided is built by combining one of the base views b Extends REST framework's `APIView` class, adding support for serialization of model instances and model querysets. +**Attributes**: + +* `model` - The model that should be used for this view. Used as a fallback for determining the serializer if `serializer_class` is not set, and as a fallback for determining the queryset if `queryset` is not set. Otherwise not required. +* `serializer_class` - The serializer class that should be used for validating and deserializing input, and for serializing output. If unset, this defaults to creating a serializer class using `self.model`, with the `DEFAULT_MODEL_SERIALIZER_CLASS` setting as the base serializer class. + ## MultipleObjectAPIView Provides a base view for acting on a single object, by combining REST framework's `APIView`, and Django's [MultipleObjectMixin]. **See also:** ccbv.co.uk documentation for [MultipleObjectMixin][multiple-object-mixin-classy]. +**Attributes**: + +* `queryset` - The queryset that should be used for returning objects from this view. If unset, defaults to the default queryset manager for `self.model`. +* `paginate_by` - The size of pages to use with paginated data. If set to `None` then pagination is turned off. If unset this uses the same value as the `PAGINATE_BY` setting, which defaults to `None`. +* `paginate_by_param` - The name of a query parameter, which can be used by the client to overide the default page size to use for pagination. If unset this uses the same value as the `PAGINATE_BY_PARAM` setting, which defaults to `None`. + ## SingleObjectAPIView Provides a base view for acting on a single object, by combining REST framework's `APIView`, and Django's [SingleObjectMixin]. **See also:** ccbv.co.uk documentation for [SingleObjectMixin][single-object-mixin-classy]. +**Attributes**: + +* `queryset` - The queryset that should be used when retrieving an object from this view. If unset, defaults to the default queryset manager for `self.model`. +* `pk_kwarg` - The URL kwarg that should be used to look up objects by primary key. Defaults to `'pk'`. [Can only be set to non-default on Django 1.4+] +* `slug_kwarg` - The URL kwarg that should be used to look up objects by a slug. Defaults to `'slug'`. [Can only be set to non-default on Django 1.4+] +* `slug_field` - The field on the model that should be used to look up objects by a slug. If used, this should typically be set to a field with `unique=True`. Defaults to `'slug'`. + --- # Mixins @@ -147,10 +165,6 @@ Provides a `.list(request, *args, **kwargs)` method, that implements listing a q Should be mixed in with [MultipleObjectAPIView]. -**Arguments**: - -* `page_size_kwarg` - Allows you to overwrite the global settings `PAGE_SIZE_KWARG` for a specific view. You can also turn it off for a specific view by setting it to `None`. Default is `page_size`. - ## CreateModelMixin Provides a `.create(request, *args, **kwargs)` method, that implements creating and saving a new model instance. diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 8fce9e4e..7884d096 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -96,11 +96,21 @@ Default: `rest_framework.serializers.ModelSerializer` Default: `rest_framework.pagination.PaginationSerializer` -## FORMAT_SUFFIX_KWARG +## FILTER_BACKEND -**TODO** +The filter backend class that should be used for generic filtering. If set to `None` then generic filtering is disabled. -Default: `'format'` +## PAGINATE_BY + +The default page size to use for pagination. If set to `None`, pagination is disabled by default. + +Default: `None` + +## PAGINATE_BY_KWARG + +The name of a query parameter, which can be used by the client to overide the default page size to use for pagination. If set to `None`, clients may not override the default page size. + +Default: `None` ## UNAUTHENTICATED_USER @@ -150,14 +160,10 @@ Default: `'accept'` Default: `'format'` -## PAGE_SIZE_KWARG - -Allows you to globally pass a page size parameter for an individual request. - -The name of the GET parameter of views which inherit ListModelMixin for requesting data with an individual page size. +## FORMAT_SUFFIX_KWARG -If the value if this setting is `None` the passing a page size is turned off by default. +**TODO** -Default: `'page_size'` +Default: `'format'` [cite]: http://www.python.org/dev/peps/pep-0020/ -- cgit v1.2.3 From 0eba278e1391604086dab1dfa1bd6ea86fea282e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 23:22:23 +0000 Subject: Improve pagination docs --- docs/api-guide/pagination.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index 597baba4..39e6a32d 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -80,23 +80,21 @@ We could now use our pagination serializer in a view like this. ## Pagination in the generic views -The generic class based views `ListAPIView` and `ListCreateAPIView` provide pagination of the returned querysets by default. You can customise this behaviour by altering the pagination style, by modifying the default number of results, or by turning pagination off completely. +The generic class based views `ListAPIView` and `ListCreateAPIView` provide pagination of the returned querysets by default. You can customise this behaviour by altering the pagination style, by modifying the default number of results, by allowing clients to override the page size using a query parameter, or by turning pagination off completely. -The default pagination style may be set globally, using the `PAGINATION_SERIALIZER` and `PAGINATE_BY` settings. For example. +The default pagination style may be set globally, using the `DEFAULT_PAGINATION_SERIALIZER_CLASS`, `PAGINATE_BY` and `PAGINATE_BY_PARAM` settings. For example. REST_FRAMEWORK = { - 'PAGINATION_SERIALIZER': ( - 'example_app.pagination.CustomPaginationSerializer', - ), - 'PAGINATE_BY': 10 + 'PAGINATE_BY': 10, + 'PAGINATE_BY_PARAM': 'page_size' } You can also set the pagination style on a per-view basis, using the `ListAPIView` generic class-based view. class PaginatedListView(ListAPIView): model = ExampleModel - pagination_serializer_class = CustomPaginationSerializer paginate_by = 10 + paginate_by_param = 'page_size' For more complex requirements such as serialization that differs depending on the requested media type you can override the `.get_paginate_by()` and `.get_pagination_serializer_class()` methods. @@ -122,4 +120,20 @@ For example, to nest a pair of links labelled 'prev' and 'next', and set the nam results_field = 'objects' +## Using your custom pagination serializer + +To have your custom pagination serializer be used by default use the `DEFAULT_PAGINATION_SERIALIZER_CLASS` setting: + + REST_FRAMEWORK = { + 'DEFAULT_PAGINATION_SERIALIZER_CLASS': + 'example_app.pagination.CustomPaginationSerializer', + } + +Alternatively, to set your custom pagination serializer on a per-view basis, use the `pagination_serializer_class` attribute on a generic class based view: + + class PaginatedListView(ListAPIView): + model = ExampleModel + pagination_serializer_class = CustomPaginationSerializer + paginate_by = 10 + [cite]: https://docs.djangoproject.com/en/dev/topics/pagination/ -- cgit v1.2.3 From 2263ed8b9409c709f6dbad2157f8debffb16c1d8 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 16 Nov 2012 23:24:36 +0000 Subject: Tweak --- docs/api-guide/pagination.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index 39e6a32d..5a35ed75 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -122,7 +122,7 @@ For example, to nest a pair of links labelled 'prev' and 'next', and set the nam ## Using your custom pagination serializer -To have your custom pagination serializer be used by default use the `DEFAULT_PAGINATION_SERIALIZER_CLASS` setting: +To have your custom pagination serializer be used by default, use the `DEFAULT_PAGINATION_SERIALIZER_CLASS` setting: REST_FRAMEWORK = { 'DEFAULT_PAGINATION_SERIALIZER_CLASS': -- cgit v1.2.3 From f131e533edf58dc8ba7b712b4c3486a3ab053ffc Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sun, 18 Nov 2012 17:57:02 +0000 Subject: Docs, docs, docs, docs, docs, docs --- docs/api-guide/generic-views.md | 18 ++++++++++++++++++ docs/api-guide/pagination.md | 5 +++-- 2 files changed, 21 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 33ec89d2..428323b8 100644 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -163,30 +163,48 @@ The mixin classes provide the actions that are used to provide the basic view be Provides a `.list(request, *args, **kwargs)` method, that implements listing a queryset. +If the queryset is populated, this returns a `200 OK` response, with a serialized representation of the queryset as the body of the response. The response data may optionally be paginated. + +If the queryset is empty this returns a `200 OK` reponse, unless the `.allow_empty` attribute on the view is set to `False`, in which case it will return a `404 Not Found`. + Should be mixed in with [MultipleObjectAPIView]. ## CreateModelMixin Provides a `.create(request, *args, **kwargs)` method, that implements creating and saving a new model instance. +If an object is created this returns a `201 Created` response, with a serialized representation of the object as the body of the response. If the representation contains a key named `url`, then the `Location` header of the response will be populated with that value. + +If the request data provided for creating the object was invalid, a `400 Bad Request` response will be returned, with the error details as the body of the response. + Should be mixed in with any [GenericAPIView]. ## RetrieveModelMixin Provides a `.retrieve(request, *args, **kwargs)` method, that implements returning an existing model instance in a response. +If an object can be retrieve this returns a `200 OK` response, with a serialized representation of the object as the body of the response. Otherwise it will return a `404 Not Found`. + Should be mixed in with [SingleObjectAPIView]. ## UpdateModelMixin Provides a `.update(request, *args, **kwargs)` method, that implements updating and saving an existing model instance. +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. + Should be mixed in with [SingleObjectAPIView]. ## DestroyModelMixin Provides a `.destroy(request, *args, **kwargs)` method, that implements deletion of an existing model instance. +If an object is deleted this returns a `204 No Content` response, otherwise it will return a `404 Not Found`. + Should be mixed in with [SingleObjectAPIView]. [cite]: https://docs.djangoproject.com/en/dev/ref/class-based-views/#base-vs-generic-views diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index 5a35ed75..ab335e6e 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -70,11 +70,12 @@ We could now use our pagination serializer in a view like this. # If page is not an integer, deliver first page. users = paginator.page(1) except EmptyPage: - # If page is out of range (e.g. 9999), deliver last page of results. + # If page is out of range (e.g. 9999), + # deliver last page of results. users = paginator.page(paginator.num_pages) serializer_context = {'request': request} - serializer = PaginatedUserSerializer(instance=users, + serializer = PaginatedUserSerializer(users, context=serializer_context) return Response(serializer.data) -- cgit v1.2.3 From de5b071d677074ab3b6b33a843c4b05ba2052a6b Mon Sep 17 00:00:00 2001 From: Jamie Matthews Date: Mon, 19 Nov 2012 17:22:17 +0000 Subject: Add SerializerMethodField --- docs/api-guide/fields.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index d1c31ecc..b19c324a 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -324,5 +324,11 @@ This field is always read-only. * `pk_url_kwarg` - The named url parameter for the pk field lookup. Default is `pk`. * `slug_url_kwarg` - The named url parameter for the slug field lookup. Default is to use the same value as given for `slug_field`. +# Other Fields + +## SerializerMethodField + +This is a read-only field gets its value by calling a method on the serializer class it's attached to. It can be used to add any sort of data to the serialized representation of your object. The field's constructor accepts a single argument, which is the name of the method on the serializer to be called. The method should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. + [cite]: http://www.python.org/dev/peps/pep-0020/ [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS -- cgit v1.2.3 From 3ab8c4966d065e930bd6e8bc6c26934ae5c5918c Mon Sep 17 00:00:00 2001 From: Jamie Matthews Date: Mon, 19 Nov 2012 17:24:08 +0000 Subject: Tweaks to SerializerMethodField docs --- docs/api-guide/fields.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index b19c324a..ebfb5d47 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -328,7 +328,7 @@ This field is always read-only. ## SerializerMethodField -This is a read-only field gets its value by calling a method on the serializer class it's attached to. It can be used to add any sort of data to the serialized representation of your object. The field's constructor accepts a single argument, which is the name of the method on the serializer to be called. The method should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. +This is a read-only field. It gets its value by calling a method on the serializer class it is attached to. It can be used to add any sort of data to the serialized representation of your object. The field's constructor accepts a single argument, which is the name of the method on the serializer to be called. The method should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. [cite]: http://www.python.org/dev/peps/pep-0020/ [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS -- cgit v1.2.3 From ce5b186ca869b693c945200581ba893123a63ce8 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 19 Nov 2012 21:42:33 +0000 Subject: Docs tweaks. --- docs/api-guide/authentication.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index a30bd22c..05575f57 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -68,7 +68,7 @@ This policy uses [HTTP Basic Authentication][basicauth], signed against a user's If successfully authenticated, `BasicAuthentication` provides the following credentials. -* `request.user` will be a `django.contrib.auth.models.User` instance. +* `request.user` will be a Django `User` instance. * `request.auth` will be `None`. **Note:** If you use `BasicAuthentication` in production you must ensure that your API is only available over `https` only. You should also ensure that your API clients will always re-request the username and password at login, and will never store those details to persistent storage. @@ -92,7 +92,7 @@ For clients to authenticate, the token key should be included in the `Authorizat If successfully authenticated, `TokenAuthentication` provides the following credentials. -* `request.user` will be a `django.contrib.auth.models.User` instance. +* `request.user` will be a Django `User` instance. * `request.auth` will be a `rest_framework.tokenauth.models.BasicToken` instance. **Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. @@ -104,7 +104,7 @@ If you want every user to have an automatically generated Token, you can simply if created: Token.objects.create(user=instance) -If you've already created some User`'s, you can run a script like this. +If you've already created some User's, you can run a script like this. from django.contrib.auth.models import User from rest_framework.authtoken.models import Token @@ -112,26 +112,29 @@ If you've already created some User`'s, you can run a script like this. for user in User.objects.all(): Token.objects.get_or_create(user=user) -When using TokenAuthentication, it may be useful to add a login view for clients to retrieve the token. - -REST framework provides a built-in login view for clients to retrieve the token called `rest_framework.authtoken.obtain_auth_token`. To use it, add a pattern to include the token login view for clients as follows: +When using TokenAuthentication, you may want to provide a mechanism for clients to obtain a token, given the username and password. +REST framework provides a built-in view to provide this behavior. To use it, add the `obtain_auth_token` view to your URLconf: urlpatterns += patterns('', url(r'^api-token-auth/', 'rest_framework.authtoken.obtain_auth_token') ) -The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. The authtoken login view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using forms or JSON: +The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. + +The `obtain_auth_token` view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using form data or JSON: { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } + ## SessionAuthentication @@ -139,7 +142,7 @@ This policy uses Django's default session backend for authentication. Session a If successfully authenticated, `SessionAuthentication` provides the following credentials. -* `request.user` will be a `django.contrib.auth.models.User` instance. +* `request.user` will be a Django `User` instance. * `request.auth` will be `None`. # Custom authentication -- cgit v1.2.3 From a44a94dd6ea2d9497264e267a0354cb684d398f6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 19 Nov 2012 22:08:38 +0000 Subject: More docs tweaking. --- docs/api-guide/authentication.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 05575f57..8ed6ef31 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -104,7 +104,7 @@ If you want every user to have an automatically generated Token, you can simply if created: Token.objects.create(user=instance) -If you've already created some User's, you can run a script like this. +If you've already created some users, you can generate tokens for all existing users like this: from django.contrib.auth.models import User from rest_framework.authtoken.models import Token @@ -112,16 +112,16 @@ If you've already created some User's, you can run a script like this. for user in User.objects.all(): Token.objects.get_or_create(user=user) -When using TokenAuthentication, you may want to provide a mechanism for clients to obtain a token, given the username and password. +When using `TokenAuthentication`, you may want to provide a mechanism for clients to obtain a token given the username and password. REST framework provides a built-in view to provide this behavior. To use it, add the `obtain_auth_token` view to your URLconf: urlpatterns += patterns('', url(r'^api-token-auth/', 'rest_framework.authtoken.obtain_auth_token') ) -The `r'^api-token-auth/'` part of pattern can actually be whatever URL you want to use. +Note that the URL part of the pattern can be whatever you want to use. -The `obtain_auth_token` view will render a JSON response when a valid `username` and `password` fields are POST'ed to the view using form data or JSON: +The `obtain_auth_token` view will return a JSON response when valid `username` and `password` fields are POSTed to the view using form data or JSON: { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } -- cgit v1.2.3 From 5f4c385a86b877217c1e1bc2eaff58206eabb747 Mon Sep 17 00:00:00 2001 From: Jamie Matthews Date: Tue, 20 Nov 2012 13:25:21 +0000 Subject: Add example use of SerializerMethodField to docs --- docs/api-guide/fields.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index ebfb5d47..914d0861 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -328,7 +328,21 @@ This field is always read-only. ## SerializerMethodField -This is a read-only field. It gets its value by calling a method on the serializer class it is attached to. It can be used to add any sort of data to the serialized representation of your object. The field's constructor accepts a single argument, which is the name of the method on the serializer to be called. The method should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. +This is a read-only field. It gets its value by calling a method on the serializer class it is attached to. It can be used to add any sort of data to the serialized representation of your object. The field's constructor accepts a single argument, which is the name of the method on the serializer to be called. The method should accept a single argument (in addition to `self`), which is the object being serialized. It should return whatever you want to be included in the serialized representation of the object. For example: + + from rest_framework import serializers + from django.contrib.auth.models import User + from django.utils.timezone import now + + class UserSerializer(serializers.ModelSerializer): + + days_since_joined = serializers.SerializerMethodField('get_days_since_joined') + + class Meta: + model = User + + def get_days_since_joined(self, obj): + return (now() - obj.date_joined).days [cite]: http://www.python.org/dev/peps/pep-0020/ [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS -- cgit v1.2.3