diff options
Diffstat (limited to 'docs/api-guide')
| -rwxr-xr-x | docs/api-guide/authentication.md | 11 | ||||
| -rw-r--r-- | docs/api-guide/fields.md | 12 | ||||
| -rwxr-xr-x | docs/api-guide/generic-views.md | 7 | ||||
| -rw-r--r-- | docs/api-guide/responses.md | 6 | ||||
| -rw-r--r-- | docs/api-guide/routers.md | 2 | ||||
| -rw-r--r-- | docs/api-guide/serializers.md | 12 | ||||
| -rw-r--r-- | docs/api-guide/settings.md | 18 | ||||
| -rw-r--r-- | docs/api-guide/viewsets.md | 16 |
8 files changed, 48 insertions, 36 deletions
diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 09491f02..8cf995b3 100755 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -303,6 +303,10 @@ The command line to test the authentication looks like: curl -H "Authorization: Bearer <your-access-token>" http://localhost:8000/api/ +### Alternative OAuth 2 implementations + +Note that [Django OAuth Toolkit][django-oauth-toolkit] is an alternative external package that also includes OAuth 2.0 support for REST framework. + --- # Custom authentication @@ -347,6 +351,10 @@ The following third party packages are also available. HTTP digest authentication is a widely implemented scheme that was intended to replace HTTP basic authentication, and which provides a simple encrypted authentication mechanism. [Juan Riaza][juanriaza] maintains the [djangorestframework-digestauth][djangorestframework-digestauth] package which provides HTTP digest authentication support for REST framework. +## Django OAuth Toolkit + +The [Django OAuth Toolkit][django-oauth-toolkit] package provides OAuth 2.0 support, and works with Python 2.7 and Python 3.3+. The package is maintained by [Evonove][evonove] and uses the excelllent [OAuthLib][oauthlib]. The package is well documented, and comes as a recommended alternative for OAuth 2.0 support. + [cite]: http://jacobian.org/writing/rest-worst-practices/ [http401]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.2 [http403]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4 @@ -365,3 +373,6 @@ HTTP digest authentication is a widely implemented scheme that was intended to r [django-oauth2-provider]: https://github.com/caffeinehit/django-oauth2-provider [django-oauth2-provider-docs]: https://django-oauth2-provider.readthedocs.org/en/latest/ [rfc6749]: http://tools.ietf.org/html/rfc6749 +[django-oauth-toolkit]: https://github.com/evonove/django-oauth-toolkit +[evonove]: https://github.com/evonove/ +[oauthlib]: https://github.com/idan/oauthlib diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 94fff7e2..d69730c9 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -214,10 +214,10 @@ In the case of JSON this means the default datetime representation uses the [ECM **Signature:** `DateTimeField(format=None, input_formats=None)` -* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that python `datetime` objects should be returned by `to_native`. In this case the datetime encoding will be determined by the renderer. +* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that Python `datetime` objects should be returned by `to_native`. In this case the datetime encoding will be determined by the renderer. * `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `DATETIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`. -DateTime format strings may either be [python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`) +DateTime format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style datetimes should be used. (eg `'2013-01-29T12:34:56.000000Z'`) ## DateField @@ -227,10 +227,10 @@ Corresponds to `django.db.models.fields.DateField` **Signature:** `DateField(format=None, input_formats=None)` -* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that python `date` objects should be returned by `to_native`. In this case the date encoding will be determined by the renderer. +* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that Python `date` objects should be returned by `to_native`. In this case the date encoding will be determined by the renderer. * `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `DATE_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`. -Date format strings may either be [python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style dates should be used. (eg `'2013-01-29'`) +Date format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style dates should be used. (eg `'2013-01-29'`) ## TimeField @@ -242,10 +242,10 @@ Corresponds to `django.db.models.fields.TimeField` **Signature:** `TimeField(format=None, input_formats=None)` -* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that python `time` objects should be returned by `to_native`. In this case the time encoding will be determined by the renderer. +* `format` - A string representing the output format. If not specified, this defaults to `None`, which indicates that Python `time` objects should be returned by `to_native`. In this case the time encoding will be determined by the renderer. * `input_formats` - A list of strings representing the input formats which may be used to parse the date. If not specified, the `TIME_INPUT_FORMATS` setting will be used, which defaults to `['iso-8601']`. -Time format strings may either be [python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style times should be used. (eg `'12:34:56.000000'`) +Time format strings may either be [Python strftime formats][strftime] which explicitly specify the format, or the special string `'iso-8601'`, which indicates that [ISO 8601][iso8601] style times should be used. (eg `'12:34:56.000000'`) ## IntegerField diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md index 20b9440b..67853ed0 100755 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -60,7 +60,7 @@ The following attributes control the basic view behavior. * `queryset` - The queryset that should be used for returning objects from this view. Typically, you must either set this attribute, or override the `get_queryset()` method. * `serializer_class` - The serializer class that should be used for validating and deserializing input, and for serializing output. Typically, you must either set this attribute, or override the `get_serializer_class()` method. -* `lookup_field` - The field that should be used to lookup individual model instances. Defaults to `'pk'`. The URL conf should include a keyword argument corresponding to this value. More complex lookup styles can be supported by overriding the `get_object()` method. +* `lookup_field` - The field that should be used to lookup individual model instances. Defaults to `'pk'`. The URL conf should include a keyword argument corresponding to this value. More complex lookup styles can be supported by overriding the `get_object()` method. Note that when using hyperlinked APIs you'll need to ensure that *both* the API views *and* the serializer classes use lookup fields that correctly correspond with the URL conf. **Shortcuts**: @@ -92,7 +92,8 @@ May be overridden to provide dynamic behavior such as returning a queryset that For example: def get_queryset(self): - return self.user.accounts.all() + user = self.request.user + return user.accounts.all() #### `get_object(self)` @@ -131,7 +132,7 @@ You may want to override this method to provide more complex behavior such as mo For example: def get_paginate_by(self): - self.request.accepted_renderer.format == 'html': + if self.request.accepted_renderer.format == 'html': return 20 return 100 diff --git a/docs/api-guide/responses.md b/docs/api-guide/responses.md index 374276dc..399b7c23 100644 --- a/docs/api-guide/responses.md +++ b/docs/api-guide/responses.md @@ -8,9 +8,9 @@ REST framework supports HTTP content negotiation by providing a `Response` class which allows you to return content that can be rendered into multiple content types, depending on the client request. -The `Response` class subclasses Django's `SimpleTemplateResponse`. `Response` objects are initialised with data, which should consist of native python primatives. REST framework then uses standard HTTP content negotiation to determine how it should render the final response content. +The `Response` class subclasses Django's `SimpleTemplateResponse`. `Response` objects are initialised with data, which should consist of native Python primitives. REST framework then uses standard HTTP content negotiation to determine how it should render the final response content. -There's no requirement for you to use the `Response` class, you can also return regular `HttpResponse` objects from your views if you want, but it provides a nicer interface for returning Web API responses. +There's no requirement for you to use the `Response` class, you can also return regular `HttpResponse` or `StreamingHttpResponse` objects from your views if required. Using the `Response` class simply provides a nicer interface for returning content-negotiated Web API responses, that can be rendered to multiple formats. Unless you want to heavily customize REST framework for some reason, you should always use an `APIView` class or `@api_view` function for views that return `Response` objects. Doing so ensures that the view can perform content negotiation and select the appropriate renderer for the response, before it is returned from the view. @@ -22,7 +22,7 @@ Unless you want to heavily customize REST framework for some reason, you should **Signature:** `Response(data, status=None, template_name=None, headers=None, content_type=None)` -Unlike regular `HttpResponse` objects, you do not instantiate `Response` objects with rendered content. Instead you pass in unrendered data, which may consist of any python primatives. +Unlike regular `HttpResponse` objects, you do not instantiate `Response` objects with rendered content. Instead you pass in unrendered data, which may consist of any Python primitives. The renderers used by the `Response` class cannot natively handle complex datatypes such as Django model instances, so you need to serialize the data into primative datatypes before creating the `Response` object. diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md index f16fa946..b74b6e13 100644 --- a/docs/api-guide/routers.md +++ b/docs/api-guide/routers.md @@ -26,7 +26,7 @@ There are two mandatory arguments to the `register()` method: Optionally, you may also specify an additional argument: -* `base_name` - The base to use for the URL names that are created. If unset the basename will be automatically generated based on the `model` or `queryset` attribute on the viewset, if it has one. +* `base_name` - The base to use for the URL names that are created. If unset the basename will be automatically generated based on the `model` or `queryset` attribute on the viewset, if it has one. Note that if the viewset does not include a `model` or `queryset` attribute then you must set `base_name` when registering the viewset. The example above would generate the following URL patterns: diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 44ee7e39..d9c23580 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -8,7 +8,7 @@ will take some serious design work. > > — Russell Keith-Magee, [Django users group][cite] -Serializers allow complex data such as querysets and model instances to be converted to native python datatypes that can then be easily rendered into `JSON`, `XML` or other content types. Serializers also provide deserialization, allowing parsed data to be converted back into complex types, after first validating the incoming data. +Serializers allow complex data such as querysets and model instances to be converted to native Python datatypes that can then be easily rendered into `JSON`, `XML` or other content types. Serializers also provide deserialization, allowing parsed data to be converted back into complex types, after first validating the incoming data. REST framework's serializers work very similarly to Django's `Form` and `ModelForm` classes. It provides a `Serializer` class which gives you a powerful, generic way to control the output of your responses, as well as a `ModelSerializer` class which provides a useful shortcut for creating serializers that deal with model instances and querysets. @@ -39,7 +39,7 @@ Declaring a serializer looks very similar to declaring a form: an existing model instance, or create a new model instance. """ if instance is not None: - instance.title = attrs.get('title', instance.title) + instance.email = attrs.get('email', instance.email) instance.content = attrs.get('content', instance.content) instance.created = attrs.get('created', instance.created) return instance @@ -57,7 +57,7 @@ We can now use `CommentSerializer` to serialize a comment, or list of comments. serializer.data # {'email': u'leila@example.com', 'content': u'foo bar', 'created': datetime.datetime(2012, 8, 22, 16, 20, 9, 822774)} -At this point we've translated the model instance into python native datatypes. To finalise the serialization process we render the data into `json`. +At this point we've translated the model instance into Python native datatypes. To finalise the serialization process we render the data into `json`. json = JSONRenderer().render(serializer.data) json @@ -65,7 +65,7 @@ At this point we've translated the model instance into python native datatypes. ## Deserializing objects -Deserialization is similar. First we parse a stream into python native datatypes... +Deserialization is similar. First we parse a stream into Python native datatypes... stream = StringIO(json) data = JSONParser().parse(stream) @@ -387,7 +387,7 @@ There needs to be a way of determining which views should be used for hyperlinki By default hyperlinks are expected to correspond to a view name that matches the style `'{model_name}-detail'`, and looks up the instance by a `pk` keyword argument. -You can change the field that is used for object lookups by setting the `lookup_field` option. The value of this option should correspond both with a kwarg in the URL conf, and with an field on the model. For example: +You can change the field that is used for object lookups by setting the `lookup_field` option. The value of this option should correspond both with a kwarg in the URL conf, and with a field on the model. For example: class AccountSerializer(serializers.HyperlinkedModelSerializer): class Meta: @@ -395,6 +395,8 @@ You can change the field that is used for object lookups by setting the `lookup_ fields = ('url', 'account_name', 'users', 'created') lookup_field = 'slug' +Not that the `lookup_field` will be used as the default on *all* hyperlinked fields, including both the URL identity, and any hyperlinked relationships. + For more specfic requirements such as specifying a different lookup for each field, you'll want to set the fields on the serializer explicitly. For example: class AccountSerializer(serializers.HyperlinkedModelSerializer): diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 8d8c00cf..4a5164c9 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -199,9 +199,9 @@ Default: `'format'` #### DATETIME_FORMAT -A format string that should be used by default for rendering the output of `DateTimeField` serializer fields. If `None`, then `DateTimeField` serializer fields will return python `datetime` objects, and the datetime encoding will be determined by the renderer. +A format string that should be used by default for rendering the output of `DateTimeField` serializer fields. If `None`, then `DateTimeField` serializer fields will return Python `datetime` objects, and the datetime encoding will be determined by the renderer. -May be any of `None`, `'iso-8601'` or a python [strftime format][strftime] string. +May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. Default: `None` @@ -209,15 +209,15 @@ Default: `None` A list of format strings that should be used by default for parsing inputs to `DateTimeField` serializer fields. -May be a list including the string `'iso-8601'` or python [strftime format][strftime] strings. +May be a list including the string `'iso-8601'` or Python [strftime format][strftime] strings. Default: `['iso-8601']` #### DATE_FORMAT -A format string that should be used by default for rendering the output of `DateField` serializer fields. If `None`, then `DateField` serializer fields will return python `date` objects, and the date encoding will be determined by the renderer. +A format string that should be used by default for rendering the output of `DateField` serializer fields. If `None`, then `DateField` serializer fields will return Python `date` objects, and the date encoding will be determined by the renderer. -May be any of `None`, `'iso-8601'` or a python [strftime format][strftime] string. +May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. Default: `None` @@ -225,15 +225,15 @@ Default: `None` A list of format strings that should be used by default for parsing inputs to `DateField` serializer fields. -May be a list including the string `'iso-8601'` or python [strftime format][strftime] strings. +May be a list including the string `'iso-8601'` or Python [strftime format][strftime] strings. Default: `['iso-8601']` #### TIME_FORMAT -A format string that should be used by default for rendering the output of `TimeField` serializer fields. If `None`, then `TimeField` serializer fields will return python `time` objects, and the time encoding will be determined by the renderer. +A format string that should be used by default for rendering the output of `TimeField` serializer fields. If `None`, then `TimeField` serializer fields will return Python `time` objects, and the time encoding will be determined by the renderer. -May be any of `None`, `'iso-8601'` or a python [strftime format][strftime] string. +May be any of `None`, `'iso-8601'` or a Python [strftime format][strftime] string. Default: `None` @@ -241,7 +241,7 @@ Default: `None` A list of format strings that should be used by default for parsing inputs to `TimeField` serializer fields. -May be a list including the string `'iso-8601'` or python [strftime format][strftime] strings. +May be a list including the string `'iso-8601'` or Python [strftime format][strftime] strings. Default: `['iso-8601']` diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md index 2783da98..25d11bfb 100644 --- a/docs/api-guide/viewsets.md +++ b/docs/api-guide/viewsets.md @@ -27,7 +27,7 @@ Let's define a simple viewset that can be used to list or retrieve all the users queryset = User.objects.all() serializer = UserSerializer(queryset, many=True) return Response(serializer.data) - + def retrieve(self, request, pk=None): queryset = User.objects.all() user = get_object_or_404(queryset, pk=pk) @@ -69,7 +69,7 @@ The default routers included with REST framework will provide routes for a stand """ Example empty viewset demonstrating the standard actions that will be handled by a router class. - + If you're using format suffixes, make sure to also include the `format=None` keyword argument for each action. """ @@ -103,12 +103,12 @@ For example: class UserViewSet(viewsets.ModelViewSet): """ - A viewset that provides the standard actions + A viewset that provides the standard actions """ queryset = User.objects.all() serializer_class = UserSerializer - - @action + + @action() def set_password(self, request, pk=None): user = self.get_object() serializer = PasswordSerializer(data=request.DATA) @@ -197,7 +197,7 @@ As with `ModelViewSet`, you'll normally need to provide at least the `queryset` Again, as with `ModelViewSet`, you can use any of the standard attributes and method overrides available to `GenericAPIView`. -# Custom ViewSet base classes +# Custom ViewSet base classes You may need to provide custom `ViewSet` classes that do not have the full set of `ModelViewSet` actions, or that customize the behavior in some other way. @@ -209,11 +209,9 @@ To create a base viewset class that provides `create`, `list` and `retrieve` ope mixins.ListMixin, mixins.RetrieveMixin, viewsets.GenericViewSet): - pass - """ A viewset that provides `retrieve`, `update`, and `list` actions. - + To use it, override the class and set the `.queryset` and `.serializer_class` attributes. """ |