From 31b585f26a8fc72e5b527b7672c7691e374dc494 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 7 Jan 2013 21:13:10 +0000 Subject: Note paginate_by=None usage. Fixes #555. --- docs/api-guide/pagination.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md index ab335e6e..71253afb 100644 --- a/docs/api-guide/pagination.md +++ b/docs/api-guide/pagination.md @@ -97,6 +97,8 @@ You can also set the pagination style on a per-view basis, using the `ListAPIVie paginate_by = 10 paginate_by_param = 'page_size' +Note that using a `paginate_by` value of `None` will turn off pagination for the view. + 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. --- -- cgit v1.2.3 From 4df1172665f6df3d4c4df53b4836e2c6ed462da5 Mon Sep 17 00:00:00 2001 From: Marc Tamlyn Date: Tue, 8 Jan 2013 11:45:55 +0000 Subject: Fix reference to BasicAuthentication in settings. --- docs/api-guide/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 8c87f2ca..a422e5f6 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -65,7 +65,7 @@ Default: ( 'rest_framework.authentication.SessionAuthentication', - 'rest_framework.authentication.UserBasicAuthentication' + 'rest_framework.authentication.BasicAuthentication' ) ## DEFAULT_PERMISSION_CLASSES -- cgit v1.2.3 From cb235977f654ce6c385cf5245cfa086c2ed54780 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 9 Jan 2013 09:22:17 +0000 Subject: Include CSRF note in SessionAuthentication docs. --- docs/api-guide/authentication.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 43fc15d2..c089e4e1 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -125,17 +125,6 @@ The `obtain_auth_token` view will return a JSON response when valid `username` a { 'token' : '9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b' } - - ## SessionAuthentication This policy uses Django's default session backend for authentication. Session authentication is appropriate for AJAX clients that are running in the same session context as your website. @@ -145,6 +134,8 @@ If successfully authenticated, `SessionAuthentication` provides the following cr * `request.user` will be a Django `User` instance. * `request.auth` will be `None`. +If you're using an AJAX style API with SessionAuthentication, you'll need to make sure you include a valid CSRF token for any "unsafe" HTTP method calls, such as `PUT`, `POST` or `DELETE` requests. See the [Django CSRF documentation][csrf-ajax] for more details. + # Custom authentication To implement a custom authentication policy, subclass `BaseAuthentication` and override the `.authenticate(self, request)` method. The method should return a two-tuple of `(user, auth)` if authentication succeeds, or `None` otherwise. @@ -154,3 +145,4 @@ To implement a custom authentication policy, subclass `BaseAuthentication` and o [oauth]: http://oauth.net/2/ [permission]: permissions.md [throttling]: throttling.md +[csrf-ajax]: https://docs.djangoproject.com/en/dev/ref/contrib/csrf/#ajax -- cgit v1.2.3 From 919c5e1e01106918af9f26c506c2198fbf731923 Mon Sep 17 00:00:00 2001 From: Stephan Groß Date: Fri, 11 Jan 2013 20:26:44 +0100 Subject: Fix typo in permission_classes --- 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 c089e4e1..afd9a261 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -52,7 +52,7 @@ Or, if you're using the `@api_view` decorator with function based views. @api_view(['GET']) @authentication_classes((SessionAuthentication, BasicAuthentication)) - @permissions_classes((IsAuthenticated,)) + @permission_classes((IsAuthenticated,)) def example_view(request, format=None): content = { 'user': unicode(request.user), # `django.contrib.auth.User` instance. -- cgit v1.2.3 From a7e7c441a4e4eb058c0b879e62d976b848b618c6 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 14 Jan 2013 17:38:32 +0000 Subject: Add link to @mjumbewu's CSV package --- docs/api-guide/renderers.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index 389dec1f..86bbdaa1 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -280,6 +280,9 @@ The following third party packages are also available. ## MessagePack [MessagePack][messagepack] is a fast, efficient binary serialization format. [Juan Riaza][juanriaza] maintains the `djangorestframework-msgpack` package which provides MessagePack renderer and parser support for REST framework. Documentation is [available here][djangorestframework-msgpack]. +## CSV + +Comma-separated values are a plain-text tabular data format, that can be easily imported into spreadsheet applications. [Mjumbe Poe][mjumbewu] maintains the [djangorestframework-csv][djangorestframework-csv] package which provides CSV renderer support for REST framework. [cite]: https://docs.djangoproject.com/en/dev/ref/template-response/#the-rendering-process [conneg]: content-negotiation.md @@ -292,4 +295,5 @@ The following third party packages are also available. [django-error-views]: https://docs.djangoproject.com/en/dev/topics/http/views/#customizing-error-views [messagepack]: https://github.com/juanriaza/django-rest-framework-msgpack [juanriaza]: https://github.com/juanriaza -[djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack \ No newline at end of file +[djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack[mjumbewu]: https://github.com/mjumbewu +[djangorestframework-csv]: https://github.com/mjumbewu/django-rest-framework-csv \ No newline at end of file -- cgit v1.2.3 From 190473f5089c5862e610bd823d6b67257ab1376f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Mon, 14 Jan 2013 17:38:45 +0000 Subject: Tweak messagepack links --- docs/api-guide/parsers.md | 2 +- docs/api-guide/renderers.md | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md index 9356b420..de968557 100644 --- a/docs/api-guide/parsers.md +++ b/docs/api-guide/parsers.md @@ -167,7 +167,7 @@ The following third party packages are also available. ## MessagePack -[MessagePack][messagepack] is a fast, efficient binary serialization format. [Juan Riaza][juanriaza] maintains the `djangorestframework-msgpack` package which provides MessagePack renderer and parser support for REST framework. Documentation is [available here][djangorestframework-msgpack]. +[MessagePack][messagepack] is a fast, efficient binary serialization format. [Juan Riaza][juanriaza] maintains the [djangorestframework-msgpack][djangorestframework-msgpack] package which provides MessagePack renderer and parser support for REST framework. [cite]: https://groups.google.com/d/topic/django-developers/dxI4qVzrBY4/discussion [messagepack]: https://github.com/juanriaza/django-rest-framework-msgpack diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index 86bbdaa1..b4f7ec3d 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -279,7 +279,8 @@ The following third party packages are also available. ## MessagePack -[MessagePack][messagepack] is a fast, efficient binary serialization format. [Juan Riaza][juanriaza] maintains the `djangorestframework-msgpack` package which provides MessagePack renderer and parser support for REST framework. Documentation is [available here][djangorestframework-msgpack]. +[MessagePack][messagepack] is a fast, efficient binary serialization format. [Juan Riaza][juanriaza] maintains the [djangorestframework-msgpack][djangorestframework-msgpack] package which provides MessagePack renderer and parser support for REST framework. + ## CSV Comma-separated values are a plain-text tabular data format, that can be easily imported into spreadsheet applications. [Mjumbe Poe][mjumbewu] maintains the [djangorestframework-csv][djangorestframework-csv] package which provides CSV renderer support for REST framework. @@ -293,7 +294,8 @@ Comma-separated values are a plain-text tabular data format, that can be easily [application/vnd.github+json]: http://developer.github.com/v3/media/ [application/vnd.collection+json]: http://www.amundsen.com/media-types/collection/ [django-error-views]: https://docs.djangoproject.com/en/dev/topics/http/views/#customizing-error-views -[messagepack]: https://github.com/juanriaza/django-rest-framework-msgpack +[messagepack]: http://msgpack.org/ [juanriaza]: https://github.com/juanriaza -[djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack[mjumbewu]: https://github.com/mjumbewu +[mjumbewu]: https://github.com/mjumbewu +[djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack [djangorestframework-csv]: https://github.com/mjumbewu/django-rest-framework-csv \ No newline at end of file -- cgit v1.2.3 From 55cc7452546f44d48fd68b81eebc1eed75eff1df Mon Sep 17 00:00:00 2001 From: Federico Capoano Date: Wed, 16 Jan 2013 17:10:46 +0100 Subject: Update docs/api-guide/authentication.md Added mod_wsgi specific instructions--- docs/api-guide/authentication.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index afd9a261..e91f6c2e 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -60,6 +60,17 @@ Or, if you're using the `@api_view` decorator with function based views. } return Response(content) +## Apache mod_wsgi Specific Configuration + +Unlike other HTTP headers, the authorisation header is not passed through to a WSGI application by default. This is the case as doing so could leak information about passwords through to a WSGI application which should not be able to see them when Apache is performing authentication... + +If it is desired that the WSGI application be responsible for handling user authentication, then it is necessary to explicitly configure mod_wsgi to pass the required headers through to the application. This can be done by specifying the WSGIPassAuthorization directive in the appropriate context and setting it to 'On'. + + # this can go in either server config, virtual host, directory or .htaccess + WSGIPassAuthorization On + +[cite]: http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIPassAuthorization + # API Reference ## BasicAuthentication -- cgit v1.2.3 From f19d4ea8b126650bc23af822acd3d6af9c7fb632 Mon Sep 17 00:00:00 2001 From: Federico Capoano Date: Wed, 16 Jan 2013 17:17:07 +0100 Subject: Update docs/api-guide/authentication.md refined mod_wsgi--- docs/api-guide/authentication.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index e91f6c2e..330cf7a4 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -62,14 +62,14 @@ Or, if you're using the `@api_view` decorator with function based views. ## Apache mod_wsgi Specific Configuration -Unlike other HTTP headers, the authorisation header is not passed through to a WSGI application by default. This is the case as doing so could leak information about passwords through to a WSGI application which should not be able to see them when Apache is performing authentication... +Unlike other HTTP headers, the authorisation header is not passed through to a WSGI application by default. This is the case as doing so could leak information about passwords through to a WSGI application which should not be able to see them when Apache is performing authentication. If it is desired that the WSGI application be responsible for handling user authentication, then it is necessary to explicitly configure mod_wsgi to pass the required headers through to the application. This can be done by specifying the WSGIPassAuthorization directive in the appropriate context and setting it to 'On'. # this can go in either server config, virtual host, directory or .htaccess WSGIPassAuthorization On -[cite]: http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIPassAuthorization +[Reference to official mod_wsgi documentation][mod_wsgi_official] # API Reference @@ -157,3 +157,4 @@ To implement a custom authentication policy, subclass `BaseAuthentication` and o [permission]: permissions.md [throttling]: throttling.md [csrf-ajax]: https://docs.djangoproject.com/en/dev/ref/contrib/csrf/#ajax +[mod_wsgi_official]: http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIPassAuthorization -- cgit v1.2.3 From bd089836a138bc845eac5f89a071d2768bcf2e0e Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 18 Jan 2013 22:01:33 +0000 Subject: Note on setting ContentType. Fixes #589. Refs #586. --- docs/api-guide/parsers.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md index de968557..3a1918f4 100644 --- a/docs/api-guide/parsers.md +++ b/docs/api-guide/parsers.md @@ -14,6 +14,18 @@ REST framework includes a number of built in Parser classes, that allow you to a The set of valid parsers for a view is always defined as a list of classes. When either `request.DATA` or `request.FILES` is accessed, REST framework will examine the `Content-Type` header on the incoming request, and determine which parser to use to parse the request content. +--- + +**Note**: When developing client applications always remember to make sure you're setting the `Content-Type` header when sending data in an HTTP request. + +If you don't set the content type, most clients will default to using `'application/x-www-form-urlencoded'`, which may not be what you wanted. + +As an example, if you are sending `json` encoded data using jQuery with the [.ajax() method][jquery-ajax], you should make sure to include the `contentType: 'application/json'` setting. + +If you're working with the API using the command line tool `curl`, you can use the `-H` flag to include a `ContentType` header. For example, to set the content type to `json` use `-H 'content-type: application/json'`. + +--- + ## Setting the parsers The default set of parsers may be set globally, using the `DEFAULT_PARSER_CLASSES` setting. For example, the following settings would allow requests with `YAML` content. @@ -169,6 +181,7 @@ The following third party packages are also available. [MessagePack][messagepack] is a fast, efficient binary serialization format. [Juan Riaza][juanriaza] maintains the [djangorestframework-msgpack][djangorestframework-msgpack] package which provides MessagePack renderer and parser support for REST framework. +[jquery-ajax]: http://api.jquery.com/jQuery.ajax/ [cite]: https://groups.google.com/d/topic/django-developers/dxI4qVzrBY4/discussion [messagepack]: https://github.com/juanriaza/django-rest-framework-msgpack [juanriaza]: https://github.com/juanriaza -- cgit v1.2.3 From 15ad94c6111735044dd6a38a9b48d23a22b8b18f Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 18 Jan 2013 22:06:41 +0000 Subject: Drop the curl notes. Unnecessary. --- docs/api-guide/parsers.md | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md index 3a1918f4..0cd01639 100644 --- a/docs/api-guide/parsers.md +++ b/docs/api-guide/parsers.md @@ -22,8 +22,6 @@ If you don't set the content type, most clients will default to using `'applicat As an example, if you are sending `json` encoded data using jQuery with the [.ajax() method][jquery-ajax], you should make sure to include the `contentType: 'application/json'` setting. -If you're working with the API using the command line tool `curl`, you can use the `-H` flag to include a `ContentType` header. For example, to set the content type to `json` use `-H 'content-type: application/json'`. - --- ## Setting the parsers -- cgit v1.2.3 From 73b69b9bb6f92f0d674c10420ac462b51cad233d Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Fri, 18 Jan 2013 22:26:36 +0000 Subject: Rephrasing. --- docs/api-guide/authentication.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 330cf7a4..c0f9c072 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -60,17 +60,15 @@ Or, if you're using the `@api_view` decorator with function based views. } return Response(content) -## Apache mod_wsgi Specific Configuration +## Apache mod_wsgi specific configuration -Unlike other HTTP headers, the authorisation header is not passed through to a WSGI application by default. This is the case as doing so could leak information about passwords through to a WSGI application which should not be able to see them when Apache is performing authentication. +Note that if deploying to [Apache using mod_wsgi][mod_wsgi_official], the authorization header is not passed through to a WSGI application by default, as it is assumed that authentication will be handled by Apache, rather than at an application level. -If it is desired that the WSGI application be responsible for handling user authentication, then it is necessary to explicitly configure mod_wsgi to pass the required headers through to the application. This can be done by specifying the WSGIPassAuthorization directive in the appropriate context and setting it to 'On'. +If you are deploying to Apache, and using any non-session based authentication, you will need to explicitly configure mod_wsgi to pass the required headers through to the application. This can be done by specifying the `WSGIPassAuthorization` directive in the appropriate context and setting it to `'On'`. # this can go in either server config, virtual host, directory or .htaccess WSGIPassAuthorization On -[Reference to official mod_wsgi documentation][mod_wsgi_official] - # API Reference ## BasicAuthentication -- cgit v1.2.3 From 9b9b6529bcf3c3f39abf398597684962e5710e57 Mon Sep 17 00:00:00 2001 From: Bruno Renié Date: Sun, 20 Jan 2013 14:49:07 +0100 Subject: Fixed reference to authtoken in the docs --- 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 c0f9c072..1b56cf44 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -102,7 +102,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 `User` instance. -* `request.auth` will be a `rest_framework.tokenauth.models.BasicToken` instance. +* `request.auth` will be a `rest_framework.authtoken.models.BasicToken` instance. **Note:** If you use `TokenAuthentication` in production you must ensure that your API is only available over `https` only. -- cgit v1.2.3