From 36cd91bbbe6bc0aeef9b1eb711415988f5c4e501 Mon Sep 17 00:00:00 2001 From: Mjumbe Wawatu Poe Date: Fri, 7 Sep 2012 14:12:46 -0400 Subject: Update docs for tokenauth --- docs/api-guide/authentication.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index ed7ac288..c5e4c1cc 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -8,7 +8,7 @@ Authentication will run the first time either the `request.user` or `request.aut The `request.user` property will typically be set to an instance of the `contrib.auth` package's `User` class. -The `request.auth` property is used for any additional authentication information, for example, it may be used to represent an authentication token that the request was signed with. +The `request.auth` property is used for any additional authentication information, for example, it may be used to represent an authentication token that the request was signed with. ## How authentication is determined @@ -36,7 +36,7 @@ You can also set the authentication policy on a per-view basis, using the `APIVi def get(self, request, format=None): content = { - 'user': unicode(request.user), # `django.contrib.auth.User` instance. + 'user': unicode(request.user), # `django.contrib.auth.User` instance. 'auth': unicode(request.auth), # None } return Response(content) @@ -49,7 +49,7 @@ Or, if you're using the `@api_view` decorator with function based views. ) def example_view(request, format=None): content = { - 'user': unicode(request.user), # `django.contrib.auth.User` instance. + 'user': unicode(request.user), # `django.contrib.auth.User` instance. 'auth': unicode(request.auth), # None } return Response(content) @@ -65,16 +65,20 @@ If successfully authenticated, `UserBasicAuthentication` provides the following * `request.user` will be a `django.contrib.auth.models.User` instance. * `request.auth` will be `None`. -## TokenBasicAuthentication +## TokenAuthentication -This policy uses [HTTP Basic Authentication][basicauth], signed against a token key and secret. Token basic authentication is appropriate for client-server setups, such as native desktop and mobile clients. +This policy uses [HTTP Authentication][basicauth] with a custom authentication scheme called "Token". Token basic authentication is appropriate for client-server setups, such as native desktop and mobile clients. The token key should be passed in as a string to the "Authorization" HTTP header. For example: -**Note:** If you run `TokenBasicAuthentication` in production your API must be `https` only, or it will be completely insecure. + curl http://my.api.org/ -X POST -H "Authorization: Token 0123456789abcdef0123456789abcdef" -If successfully authenticated, `TokenBasicAuthentication` provides the following credentials. +**Note:** If you run `TokenAuthentication` in production your API must be `https` only, or it will be completely insecure. + +If successfully authenticated, `TokenAuthentication` provides the following credentials. * `request.user` will be a `django.contrib.auth.models.User` instance. -* `request.auth` will be a `djangorestframework.models.BasicToken` instance. +* `request.auth` will be a `djangorestframework.tokenauth.models.Token` instance. + +To use the `TokenAuthentication` scheme, you must have a token model. Django REST Framework comes with a minimal default token model. To use it, include `djangorestframework.tokenauth` in your installed applications. To use your own token model, subclass the `djangorestframework.tokenauth.authentication.TokenAuthentication` class and specify a `model` attribute that references your custom token model. The token model must provide `user`, `key`, and `revoked` attributes. For convenience, the `djangorestframework.tokenauth.models.BaseToken` abstract model implements this minimum contract, and also randomly populates the key field when none is provided. ## OAuthAuthentication -- cgit v1.2.3 From 3b1404bd7d37d8c60cf45071852f86eea8d4c68f Mon Sep 17 00:00:00 2001 From: Mjumbe Wawatu Poe Date: Fri, 7 Sep 2012 14:23:53 -0400 Subject: Rename the default token class to "BasicToken" --- 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 c5e4c1cc..c5b7ac9c 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -76,7 +76,7 @@ This policy uses [HTTP Authentication][basicauth] with a custom authentication s If successfully authenticated, `TokenAuthentication` provides the following credentials. * `request.user` will be a `django.contrib.auth.models.User` instance. -* `request.auth` will be a `djangorestframework.tokenauth.models.Token` instance. +* `request.auth` will be a `djangorestframework.tokenauth.models.BasicToken` instance. To use the `TokenAuthentication` scheme, you must have a token model. Django REST Framework comes with a minimal default token model. To use it, include `djangorestframework.tokenauth` in your installed applications. To use your own token model, subclass the `djangorestframework.tokenauth.authentication.TokenAuthentication` class and specify a `model` attribute that references your custom token model. The token model must provide `user`, `key`, and `revoked` attributes. For convenience, the `djangorestframework.tokenauth.models.BaseToken` abstract model implements this minimum contract, and also randomly populates the key field when none is provided. -- cgit v1.2.3 From f741cdae44bc455089a5ed7e1dbea4760ca97b85 Mon Sep 17 00:00:00 2001 From: Mjumbe Wawatu Poe Date: Fri, 7 Sep 2012 16:12:33 -0400 Subject: Move TokenAuthentication class into djangorestframework.authentication --- docs/api-guide/authentication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index c5b7ac9c..5f176d02 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -67,9 +67,9 @@ If successfully authenticated, `UserBasicAuthentication` provides the following ## TokenAuthentication -This policy uses [HTTP Authentication][basicauth] with a custom authentication scheme called "Token". Token basic authentication is appropriate for client-server setups, such as native desktop and mobile clients. The token key should be passed in as a string to the "Authorization" HTTP header. For example: +This policy uses [HTTP Authentication][basicauth] with no authentication scheme. Token basic authentication is appropriate for client-server setups, such as native desktop and mobile clients. The token key should be passed in as a string to the "Authorization" HTTP header. For example: - curl http://my.api.org/ -X POST -H "Authorization: Token 0123456789abcdef0123456789abcdef" + curl http://my.api.org/ -X POST -H "Authorization: 0123456789abcdef0123456789abcdef" **Note:** If you run `TokenAuthentication` in production your API must be `https` only, or it will be completely insecure. @@ -78,7 +78,7 @@ If successfully authenticated, `TokenAuthentication` provides the following cred * `request.user` will be a `django.contrib.auth.models.User` instance. * `request.auth` will be a `djangorestframework.tokenauth.models.BasicToken` instance. -To use the `TokenAuthentication` scheme, you must have a token model. Django REST Framework comes with a minimal default token model. To use it, include `djangorestframework.tokenauth` in your installed applications. To use your own token model, subclass the `djangorestframework.tokenauth.authentication.TokenAuthentication` class and specify a `model` attribute that references your custom token model. The token model must provide `user`, `key`, and `revoked` attributes. For convenience, the `djangorestframework.tokenauth.models.BaseToken` abstract model implements this minimum contract, and also randomly populates the key field when none is provided. +To use the `TokenAuthentication` policy, you must have a token model. Django REST Framework comes with a minimal default token model. To use it, include `djangorestframework.tokenauth` in your installed applications and sync your database. To use your own token model, subclass the `djangorestframework.tokenauth.TokenAuthentication` class and specify a `model` attribute that references your custom token model. The token model must provide `user`, `key`, and `revoked` attributes. For convenience, the `djangorestframework.tokenauth.models.BaseToken` abstract model implements this minimum contract, and also randomly populates the key field when none is provided. ## OAuthAuthentication -- cgit v1.2.3 From 8df71f4d1d9a8a3df8e053d99340fbe5bf78b8ad Mon Sep 17 00:00:00 2001 From: Mjumbe Wawatu Poe Date: Fri, 7 Sep 2012 16:19:15 -0400 Subject: Get rid of the BaseToken abstract model --- 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 5f176d02..45da2c55 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -78,7 +78,7 @@ If successfully authenticated, `TokenAuthentication` provides the following cred * `request.user` will be a `django.contrib.auth.models.User` instance. * `request.auth` will be a `djangorestframework.tokenauth.models.BasicToken` instance. -To use the `TokenAuthentication` policy, you must have a token model. Django REST Framework comes with a minimal default token model. To use it, include `djangorestframework.tokenauth` in your installed applications and sync your database. To use your own token model, subclass the `djangorestframework.tokenauth.TokenAuthentication` class and specify a `model` attribute that references your custom token model. The token model must provide `user`, `key`, and `revoked` attributes. For convenience, the `djangorestframework.tokenauth.models.BaseToken` abstract model implements this minimum contract, and also randomly populates the key field when none is provided. +To use the `TokenAuthentication` policy, you must have a token model. Django REST Framework comes with a minimal default token model. To use it, include `djangorestframework.tokenauth` in your installed applications and sync your database. To use your own token model, subclass the `djangorestframework.tokenauth.TokenAuthentication` class and specify a `model` attribute that references your custom token model. The token model must provide `user`, `key`, and `revoked` attributes. Refer to the `djangorestframework.tokenauth.models.BasicToken` model as an example. ## OAuthAuthentication -- cgit v1.2.3 From 247696e820dfe4535b3141d744129d654f9b6aea Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 8 Sep 2012 22:06:13 +0100 Subject: Links to source files in docs --- docs/api-guide/authentication.md | 2 ++ docs/api-guide/exceptions.md | 2 ++ docs/api-guide/parsers.md | 2 ++ docs/api-guide/permissions.md | 2 ++ docs/api-guide/renderers.md | 2 ++ docs/api-guide/requests.md | 2 ++ docs/api-guide/responses.md | 2 ++ docs/api-guide/reverse.md | 2 ++ docs/api-guide/serializers.md | 2 ++ docs/api-guide/settings.md | 2 ++ docs/api-guide/status-codes.md | 2 ++ docs/api-guide/throttling.md | 2 ++ docs/api-guide/views.md | 2 ++ 13 files changed, 26 insertions(+) (limited to 'docs/api-guide') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md index 45da2c55..ca29bc4d 100644 --- a/docs/api-guide/authentication.md +++ b/docs/api-guide/authentication.md @@ -1,3 +1,5 @@ + + # Authentication Authentication is the mechanism of associating an incoming request with a set of identifying credentials, such as the user the request came from, or the token that it was signed with. The [permission] and [throttling] policies can then use those credentials to determine if the request should be permitted. diff --git a/docs/api-guide/exceptions.md b/docs/api-guide/exceptions.md index d41327c6..bb3ed56e 100644 --- a/docs/api-guide/exceptions.md +++ b/docs/api-guide/exceptions.md @@ -1,3 +1,5 @@ + + # Exceptions diff --git a/docs/api-guide/parsers.md b/docs/api-guide/parsers.md index 2edc11de..5e2344a3 100644 --- a/docs/api-guide/parsers.md +++ b/docs/api-guide/parsers.md @@ -1,3 +1,5 @@ + + # Parsers ## .parse(request) diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index 8b137891..2e15107c 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -1 +1,3 @@ + +# Permissions \ No newline at end of file diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index 5a66da69..1cd6d1a0 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -1,3 +1,5 @@ + + # Renderers ## .render(response) diff --git a/docs/api-guide/requests.md b/docs/api-guide/requests.md index 67ddfdac..6746bb20 100644 --- a/docs/api-guide/requests.md +++ b/docs/api-guide/requests.md @@ -1,3 +1,5 @@ + + # Requests > If you're doing REST-based web service stuff ... you should ignore request.POST. diff --git a/docs/api-guide/responses.md b/docs/api-guide/responses.md index 38f6e8cb..6c279f17 100644 --- a/docs/api-guide/responses.md +++ b/docs/api-guide/responses.md @@ -1,3 +1,5 @@ + + # Responses > Unlike basic HttpResponse objects, TemplateResponse objects retain the details of the context that was provided by the view to compute the response. The final output of the response is not computed until it is needed, later in the response process. diff --git a/docs/api-guide/reverse.md b/docs/api-guide/reverse.md index 5a1d6e26..6e42b68e 100644 --- a/docs/api-guide/reverse.md +++ b/docs/api-guide/reverse.md @@ -1,3 +1,5 @@ + + # Returning URIs from your Web APIs > The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components. diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 377b0c10..38a1e560 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -1,3 +1,5 @@ + + # Serializers > Expanding the usefulness of the serializers is something that we would diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 1411b9ec..ae8dce76 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -1,3 +1,5 @@ + + # Settings Configuration for REST framework is all namespaced inside the `API_SETTINGS` setting. diff --git a/docs/api-guide/status-codes.md b/docs/api-guide/status-codes.md index c1d45905..6693c79f 100644 --- a/docs/api-guide/status-codes.md +++ b/docs/api-guide/status-codes.md @@ -1,3 +1,5 @@ + + # Status Codes > 418 I'm a teapot - Any attempt to brew coffee with a teapot should result in the error code "418 I'm a teapot". The resulting entity body MAY be short and stout. diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md index 8b137891..e3a66c83 100644 --- a/docs/api-guide/throttling.md +++ b/docs/api-guide/throttling.md @@ -1 +1,3 @@ + +# Throttling diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md index dd1dbebe..43924544 100644 --- a/docs/api-guide/views.md +++ b/docs/api-guide/views.md @@ -1,3 +1,5 @@ + + > Django's class based views are a welcome departure from the old-style views. > > — [Reinout van Rees][cite] -- cgit v1.2.3 From b5e07abc15f0937263e183b7800f30b558e37a1b Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Sat, 8 Sep 2012 22:13:11 +0100 Subject: Move quote below title for consistency --- docs/api-guide/views.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/api-guide') diff --git a/docs/api-guide/views.md b/docs/api-guide/views.md index 43924544..04647f91 100644 --- a/docs/api-guide/views.md +++ b/docs/api-guide/views.md @@ -1,11 +1,11 @@ +# Views + > Django's class based views are a welcome departure from the old-style views. > > — [Reinout van Rees][cite] -# Views - REST framework provides a simple `APIView` class, built on Django's `django.generics.views.View`. The `APIView` class ensures five main things: 1. Any requests inside the view will become `Request` instances. -- cgit v1.2.3