From 7eefcf7e53f2bc37733a601041f23d354c7729f5 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 25 Mar 2013 20:26:34 +0000 Subject: Bulk update, allow_add_remove flag --- docs/api-guide/serializers.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 42e81cad..aaff760e 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -242,17 +242,17 @@ This allows you to write views that update or create multiple items when a `PUT` # True serialize.save() # `.save()` will be called on each updated or newly created instance. -Bulk updates will update any instances that already exist, and create new instances for data items that do not have a corresponding instance. +By default bulk updates will be limited to updating instances that already exist in the provided queryset. -When performing a bulk update you may want any items that are not present in the incoming data to be deleted. To do so, pass `allow_delete=True` to the serializer. +When performing a bulk update you may want to allow new items to be created, and missing items to be deleted. To do so, pass `allow_add_remove=True` to the serializer. - serializer = BookSerializer(queryset, data=data, many=True, allow_delete=True) + serializer = BookSerializer(queryset, data=data, many=True, allow_add_remove=True) serializer.is_valid() # True - serializer.save() # `.save()` will be called on each updated or newly created instance. + serializer.save() # `.save()` will be called on updated or newly created instances. # `.delete()` will be called on any other items in the `queryset`. -Passing `allow_delete=True` ensures that any update operations will completely overwrite the existing queryset, rather than simply updating any objects found in the incoming data. +Passing `allow_delete=True` ensures that any update operations will completely overwrite the existing queryset, rather than simply updating existing objects. #### How identity is determined when performing bulk updates -- cgit v1.2.3 From 8387cb5d1655e4d29cf8bca1919038091427e584 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 25 Mar 2013 20:28:17 +0000 Subject: Docs fix --- docs/api-guide/serializers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index aaff760e..dfa0cace 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -252,7 +252,7 @@ When performing a bulk update you may want to allow new items to be created, and serializer.save() # `.save()` will be called on updated or newly created instances. # `.delete()` will be called on any other items in the `queryset`. -Passing `allow_delete=True` ensures that any update operations will completely overwrite the existing queryset, rather than simply updating existing objects. +Passing `allow_add_remove=True` ensures that any update operations will completely overwrite the existing queryset, rather than simply updating existing objects. #### How identity is determined when performing bulk updates -- cgit v1.2.3 From 92c929094c88125ea4a2fd359ec99d2b4114f081 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 26 Mar 2013 07:48:53 +0000 Subject: Version 2.2.5 --- docs/api-guide/fields.md | 7 ++++++- docs/api-guide/serializers.md | 2 +- 2 files changed, 7 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 02876936..42f89f46 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -197,12 +197,16 @@ If you want to override this behavior, you'll need to declare the `DateTimeField class Meta: model = Comment +Note that by default, datetime representations are deteremined by the renderer in use, although this can be explicitly overridden as detailed below. + +In the case of JSON this means the default datetime representation uses the [ECMA 262 date time string specification][ecma262]. This is a subset of ISO 8601 which uses millisecond precision, and includes the 'Z' suffix for the UTC timezone, for example: `2013-01-29T12:34:56.123Z`. + **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. * `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 specifiy 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.000000'`) +DateTime format strings may either be [python strftime formats][strftime] which explicitly specifiy 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 @@ -318,5 +322,6 @@ As an example, let's create a field that can be used represent the class name of [cite]: https://docs.djangoproject.com/en/dev/ref/forms/api/#django.forms.Form.cleaned_data [FILE_UPLOAD_HANDLERS]: https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-FILE_UPLOAD_HANDLERS +[ecma262]: http://ecma-international.org/ecma-262/5.1/#sec-15.9.1.15 [strftime]: http://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior [iso8601]: http://www.w3.org/TR/NOTE-datetime diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index dfa0cace..1a3c3431 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -256,7 +256,7 @@ Passing `allow_add_remove=True` ensures that any update operations will complete #### How identity is determined when performing bulk updates -Performing a bulk update is slightly more complicated than performing a bulk creation, because the serializer needs a way of determining how the items in the incoming data should be matched against the existing object instances. +Performing a bulk update is slightly more complicated than performing a bulk creation, because the serializer needs a way to determine how the items in the incoming data should be matched against the existing object instances. By default the serializer class will use the `id` key on the incoming data to determine the canonical identity of an object. If you need to change this behavior you should override the `get_identity` method on the `Serializer` class. For example: -- cgit v1.2.3 From b2cea84fae4f721e8eb6432b3d1bab1309e21a00 Mon Sep 17 00:00:00 2001 From: Fernando Rocha Date: Wed, 27 Mar 2013 19:00:36 -0300 Subject: Complete remove of client checks from oauth2 Signed-off-by: Fernando Rocha --- docs/api-guide/authentication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 541c6575..f1dd6f5f 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -294,7 +294,7 @@ The only thing needed to make the `OAuth2Authentication` class work is to insert The command line to test the authentication looks like: - curl -H "Authorization: Bearer " http://localhost:8000/api/?client_id=YOUR_CLIENT_ID\&client_secret=YOUR_CLIENT_SECRET + curl -H "Authorization: Bearer " http://localhost:8000/api/ --- -- cgit v1.2.3 From d243538547982781635e01d9b6e74afbbd628e16 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Thu, 28 Mar 2013 14:54:42 +0000 Subject: Note on using curl with token auth --- docs/api-guide/authentication.md | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 541c6575..757b8673 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -119,6 +119,8 @@ To use the `TokenAuthentication` scheme, include `rest_framework.authtoken` in y ... 'rest_framework.authtoken' ) + +Make sure to run `manage.py syncdb` after changing your settings. You'll also need to create tokens for your users. @@ -140,6 +142,10 @@ Unauthenticated responses that are denied permission will result in an `HTTP 401 WWW-Authenticate: Token +The `curl` command line tool may be useful for testing token authenticated APIs. For example: + + curl -X GET http://127.0.0.1:8000/api/example/ -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' + --- **Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. -- cgit v1.2.3 From 33ce7dfac4c9279ad6035d520a421cc7d77ffae5 Mon Sep 17 00:00:00 2001 From: Victor Shih Date: Sat, 30 Mar 2013 20:28:27 -0700 Subject: Spelling/grammar fixes. --- docs/api-guide/generic-views.md | 2 +- docs/api-guide/serializers.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) mode change 100644 => 100755 docs/api-guide/generic-views.md mode change 100644 => 100755 docs/api-guide/serializers.md (limited to 'docs/api-guide') diff --git a/docs/api-guide/generic-views.md b/docs/api-guide/generic-views.md old mode 100644 new mode 100755 index 20f1be63..cef9a9d4 --- a/docs/api-guide/generic-views.md +++ b/docs/api-guide/generic-views.md @@ -200,7 +200,7 @@ Should be mixed in with any [GenericAPIView]. 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`. +If an object can be retrieved 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]. diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md old mode 100644 new mode 100755 index 1a3c3431..2797b5f5 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -353,7 +353,7 @@ The `depth` option should be set to an integer value that indicates the depth of ## Specifying which fields should be read-only -You may wish to specify multiple fields as read-only. Instead of adding each field explicitely with the `read_only=True` attribute, you may use the `read_only_fields` Meta option, like so: +You may wish to specify multiple fields as read-only. Instead of adding each field explicitly with the `read_only=True` attribute, you may use the `read_only_fields` Meta option, like so: class AccountSerializer(serializers.ModelSerializer): class Meta: -- cgit v1.2.3 From b73dfb9cc15e96994c4d6a5ff8b2a18538bcaf74 Mon Sep 17 00:00:00 2001 From: Victor Shih Date: Wed, 10 Apr 2013 22:00:40 -0700 Subject: Remove redundant text. --- docs/api-guide/authentication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) mode change 100644 => 100755 docs/api-guide/authentication.md (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md old mode 100644 new mode 100755 index 0eea31d7..1f08f542 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -107,7 +107,7 @@ Unauthenticated responses that are denied permission will result in an `HTTP 401 WWW-Authenticate: Basic realm="api" -**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. +**Note:** If you use `BasicAuthentication` in production you must ensure that your API is only available over `https`. 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. ## TokenAuthentication @@ -148,7 +148,7 @@ The `curl` command line tool may be useful for testing token authenticated APIs. --- -**Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. +**Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https`. --- @@ -259,7 +259,7 @@ Finally, sync your database. --- -**Note:** If you use `OAuth2Authentication` in production you must ensure that your API is only available over `https` only. +**Note:** If you use `OAuth2Authentication` in production you must ensure that your API is only available over `https`. --- -- cgit v1.2.3