Auth needs to be pluggable.
— Jacob Kaplan-Moss, "REST worst practices"
-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.
+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.
REST framework provides a number of authentication schemes out of the box, and also allows you to implement custom schemes.
Authentication is always run at the very start of the view, before the permission and throttling checks occur, and before any other code is allowed to proceed.
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.
Note: Don't forget that authentication by itself won't allow or disallow an incoming request, it simply identifies the credentials that the request was made with.
-For information on how to setup the permission polices for your API please see the permissions documentation.
+For information on how to setup the permission polices for your API please see the permissions documentation.
How authentication is determined
The authentication schemes are always defined as a list of classes. REST framework will attempt to authenticate with each class in the list, and will set request.user and request.auth using the return value of the first class that successfully authenticates.
AuthenticationFailed
Signature: AuthenticationFailed(detail=None)
Raised when an incoming request includes incorrect authentication.
-By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See the authentication documentation for more details.
+By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See the authentication documentation for more details.
NotAuthenticated
Signature: NotAuthenticated(detail=None)
Raised when an unauthenticated request fails the permission checks.
-By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See the authentication documentation for more details.
+By default this exception results in a response with the HTTP status code "401 Unauthenticated", but it may also result in a "403 Forbidden" response, depending on the authentication scheme in use. See the authentication documentation for more details.
PermissionDenied
Signature: PermissionDenied(detail=None)
Raised when an authenticated request fails the permission checks.
diff --git a/api-guide/fields.html b/api-guide/fields.html index 90581f27d..dae3cc692 100644 --- a/api-guide/fields.html +++ b/api-guide/fields.html @@ -4,6 +4,7 @@Authentication or identification by itself is not usually sufficient to gain access to information or code. For that, the entity requesting access must have authorization.
— Apple Developer Documentation
-Together with authentication and throttling, permissions determine whether a request should be granted or denied access.
+Together with authentication and throttling, permissions determine whether a request should be granted or denied access.
Permission checks are always run at the very start of the view, before any other code is allowed to proceed. Permission checks will typically use the authentication information in the request.user and request.auth properties to determine if the incoming request should be permitted.
How permissions are determined
Permissions in REST framework are always defined as a list of permission classes.
@@ -338,7 +339,7 @@ else:Note: In versions 2.0 and 2.1, the signature for the permission checks always included an optional obj parameter, like so: .has_permission(self, request, view, obj=None). The method would be called twice, first for the global permission checks, with no object supplied, and second for the object-level check when required.
As of version 2.2 this signature has now been replaced with two separate method calls, which is more explicit and obvious. The old style signature continues to work, but its use will result in a PendingDeprecationWarning, which is silent by default. In 2.3 this will be escalated to a DeprecationWarning, and in 2.4 the old-style signature will be removed.
For more details see the 2.2 release announcement.
+For more details see the 2.2 release announcement.
Examples
The following is an example of a permission class that checks the incoming request's IP address against a blacklist, and denies the request if the IP has been blacklisted.
@@ -371,7 +372,7 @@ class BlacklistPermission(permissions.BasePermission): return obj.owner == request.userNote that the generic views will check the appropriate object level permissions, but if you're writing your own custom views, you'll need to make sure you check the object level permission checks yourself. You can do so by calling self.check_object_permissions(request, obj) from the view once you have the object instance. This call will raise an appropriate APIException if any object-level permission checks fail, and will otherwise simply return.
Also note that the generic views will only check the object-level permissions for views that retrieve a single model instance. If you require object-level filtering of list views, you'll need to filter the queryset separately. See the filtering documentation for more details.
+Also note that the generic views will only check the object-level permissions for views that retrieve a single model instance. If you require object-level filtering of list views, you'll need to filter the queryset separately. See the filtering documentation for more details.
Third party packages
The following third party packages are also available.
diff --git a/api-guide/relations.html b/api-guide/relations.html index 33805a02b..d4bdc3931 100644 --- a/api-guide/relations.html +++ b/api-guide/relations.html @@ -4,6 +4,7 @@How the renderer is determined
The set of valid renderers for a view is always defined as a list of classes. When a view is entered REST framework will perform content negotiation on the incoming request, and determine the most appropriate renderer to satisfy the request.
The basic process of content negotiation involves examining the request's Accept header, to determine which media types it expects in the response. Optionally, format suffixes on the URL may be used to explicitly request a particular representation. For example the URL http://example.com/api/users_count.json might be an endpoint that always returns JSON data.
For more information see the documentation on content negotiation.
+For more information see the documentation on content negotiation.
Setting the renderers
The default set of renderers may be set globally, using the DEFAULT_RENDERER_CLASSES setting. For example, the following settings would use YAML as the main media type and also include the self describing API.
REST_FRAMEWORK = {
@@ -309,7 +310,7 @@ def user_count_view(request, format=None):
JSONPRenderer
Renders the request data into JSONP. The JSONP media type provides a mechanism of allowing cross-domain AJAX requests, by wrapping a JSON response in a javascript callback.
The javascript callback function must be set by the client including a callback URL query parameter. For example http://example.com/api/users?callback=jsonpCallback. If the callback function is not explicitly set by the client it will default to 'callback'.
-Note: If you require cross-domain AJAX requests, you may want to consider using the more modern approach of CORS as an alternative to JSONP. See the CORS documentation for more details.
+Note: If you require cross-domain AJAX requests, you may want to consider using the more modern approach of CORS as an alternative to JSONP. See the CORS documentation for more details.
.media_type: application/javascript
.format: '.jsonp'
.charset: utf-8
@@ -388,7 +389,7 @@ def simple_html_view(request):
return JSONRenderer()
MultiPartRenderer
-This renderer is used for rendering HTML multipart form data. It is not suitable as a response renderer, but is instead used for creating test requests, using REST framework's test client and test request factory.
+This renderer is used for rendering HTML multipart form data. It is not suitable as a response renderer, but is instead used for creating test requests, using REST framework's test client and test request factory.
.media_type: multipart/form-data; boundary=BoUnDaRyStRiNg
.format: '.multipart'
.charset: utf-8
POST, meaning that you can access the content of PUT and PATCH requests.For more details see the parsers documentation.
+For more details see the parsers documentation.
.FILES
request.FILES returns any uploaded files that may be present in the content of the request body. This is the same as the standard HttpRequest behavior, except that the same flexible request parsing is used for request.DATA.
For more details see the parsers documentation.
+For more details see the parsers documentation.
.QUERY_PARAMS
request.QUERY_PARAMS is a more correctly named synonym for request.GET.
For clarity inside your code, we recommend using request.QUERY_PARAMS instead of the usual request.GET, as any HTTP method type may include query parameters.
.user
request.user typically returns an instance of django.contrib.auth.models.User, although the behavior depends on the authentication policy being used.
If the request is unauthenticated the default value of request.user is an instance of django.contrib.auth.models.AnonymousUser.
For more details see the authentication documentation.
+For more details see the authentication documentation.
.auth
request.auth returns any additional authentication context. The exact behavior of request.auth depends on the authentication policy being used, but it may typically be an instance of the token that the request was authenticated against.
If the request is unauthenticated, or if no additional context is present, the default value of request.auth is None.
For more details see the authentication documentation.
+For more details see the authentication documentation.
.authenticators
The APIView class or @api_view decorator will ensure that this property is automatically set to a list of Authentication instances, based on the authentication_classes set on the view or based on the DEFAULT_AUTHENTICATORS setting.
You won't typically need to access this property.
@@ -266,17 +267,17 @@.method
request.method returns the uppercased string representation of the request's HTTP method.
Browser-based PUT, PATCH and DELETE forms are transparently supported.
For more information see the browser enhancements documentation.
+For more information see the browser enhancements documentation.
.content_type
request.content_type, returns a string object representing the media type of the HTTP request's body, or an empty string if no media type was provided.
You won't typically need to directly access the request's content type, as you'll normally rely on REST framework's default request parsing behavior.
If you do need to access the content type of the request you should use the .content_type property in preference to using request.META.get('HTTP_CONTENT_TYPE'), as it provides transparent support for browser-based non-form content.
For more information see the browser enhancements documentation.
+For more information see the browser enhancements documentation.
.stream
request.stream returns a stream representing the content of the request body.
You won't typically need to directly access the request's content, as you'll normally rely on REST framework's default request parsing behavior.
If you do need to access the raw content directly, you should use the .stream property in preference to using request.content, as it provides transparent support for browser-based non-form content.
For more information see the browser enhancements documentation.
+For more information see the browser enhancements documentation.
Standard HttpRequest attributes
As REST framework's Request extends Django's HttpRequest, all the other standard attributes and methods are also available. For example the request.META and request.session dictionaries are available as normal.
Arguments:
data: The serialized data for the response.
-status: A status code for the response. Defaults to 200. See also status codes.
+status: A status code for the response. Defaults to 200. See also status codes.template_name: A template name to use ifHTMLRendereris selected.headers: A dictionary of HTTP headers to use in the response.content_type: The content type of the response. Typically, this will be set automatically by the renderer as determined by content negotiation, but there may be some cases where you need to specify the content type explicitly.
diff --git a/api-guide/reverse.html b/api-guide/reverse.html
index d6b37f873..172ef1e85 100644
--- a/api-guide/reverse.html
+++ b/api-guide/reverse.html
@@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics diff --git a/api-guide/routers.html b/api-guide/routers.html index 4654a8f0f..e3d212da5 100644 --- a/api-guide/routers.html +++ b/api-guide/routers.html @@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics diff --git a/api-guide/serializers.html b/api-guide/serializers.html index 96340bcb9..39ca749c6 100644 --- a/api-guide/serializers.html +++ b/api-guide/serializers.html @@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics @@ -524,7 +525,7 @@ The
- Tutorial
- API Guide
- Topics diff --git a/api-guide/status-codes.html b/api-guide/status-codes.html index c806bde54..c6a3dea89 100644 --- a/api-guide/status-codes.html +++ b/api-guide/status-codes.html @@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics diff --git a/api-guide/testing.html b/api-guide/testing.html index a289e2bde..7f90df040 100644 --- a/api-guide/testing.html +++ b/api-guide/testing.html @@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics diff --git a/api-guide/throttling.html b/api-guide/throttling.html index 5358b0a9f..7f8539f09 100644 --- a/api-guide/throttling.html +++ b/api-guide/throttling.html @@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics @@ -213,7 +214,7 @@
- Tutorial
- API Guide
- Topics @@ -296,9 +297,9 @@ This method is used to enforce permissions and throttling, and perform content n def hello_world(request): return Response({"message": "Hello, world!"}) -
- Tutorial
- API Guide
- Topics diff --git a/index.html b/index.html index af272a2da..7582f4f8d 100644 --- a/index.html +++ b/index.html @@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics @@ -224,9 +225,9 @@
- The Web browseable API is a huge usability win for your developers. -
- Authentication policies including OAuth1a and OAuth2 out of the box. -
- Serialization that supports both ORM and non-ORM data sources. -
- Customizable all the way down - just use regular function-based views if you don't need the more powerful features. +
- Authentication policies including OAuth1a and OAuth2 out of the box. +
- Serialization that supports both ORM and non-ORM data sources. +
- Customizable all the way down - just use regular function-based views if you don't need the more powerful features.
- Extensive documentation, and great community support.
- 1 - Serialization -
- 2 - Requests & Responses -
- 3 - Class based views -
- 4 - Authentication & permissions -
- 5 - Relationships & hyperlinked APIs -
- 6 - Viewsets & routers +
- 1 - Serialization +
- 2 - Requests & Responses +
- 3 - Class based views +
- 4 - Authentication & permissions +
- 5 - Relationships & hyperlinked APIs +
- 6 - Viewsets & routers
- Requests -
- Responses -
- Views -
- Generic views -
- Viewsets -
- Routers -
- Parsers -
- Renderers -
- Serializers -
- Serializer fields -
- Serializer relations -
- Authentication -
- Permissions -
- Throttling -
- Filtering -
- Pagination -
- Content negotiation -
- Format suffixes -
- Returning URLs -
- Exceptions -
- Status codes -
- Testing -
- Settings +
- Requests +
- Responses +
- Views +
- Generic views +
- Viewsets +
- Routers +
- Parsers +
- Renderers +
- Serializers +
- Serializer fields +
- Serializer relations +
- Authentication +
- Permissions +
- Throttling +
- Filtering +
- Pagination +
- Content negotiation +
- Format suffixes +
- Returning URLs +
- Exceptions +
- Status codes +
- Testing +
- Settings
- Documenting your API -
- AJAX, CSRF & CORS -
- Browser enhancements -
- The Browsable API -
- REST, Hypermedia & HATEOAS -
- 2.0 Announcement -
- 2.2 Announcement -
- 2.3 Announcement -
- Release Notes -
- Credits +
- Documenting your API +
- AJAX, CSRF & CORS +
- Browser enhancements +
- The Browsable API +
- REST, Hypermedia & HATEOAS +
- 2.0 Announcement +
- 2.2 Announcement +
- 2.3 Announcement +
- Release Notes +
- Credits
- Tutorial
- API Guide
- Topics diff --git a/topics/2.3-announcement.html b/topics/2.3-announcement.html index 82c2f8d0a..3ac50d6d5 100644 --- a/topics/2.3-announcement.html +++ b/topics/2.3-announcement.html @@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics @@ -217,7 +218,7 @@
- Tutorial
- API Guide
- Topics diff --git a/topics/browsable-api.html b/topics/browsable-api.html index 88165d490..f85235117 100644 --- a/topics/browsable-api.html +++ b/topics/browsable-api.html @@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics @@ -208,7 +209,7 @@
- Tutorial
- API Guide
- Topics diff --git a/topics/contributing.html b/topics/contributing.html index 4c96c60c8..7170c91d5 100644 --- a/topics/contributing.html +++ b/topics/contributing.html @@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics diff --git a/tutorial/quickstart.html b/tutorial/quickstart.html index 079177cef..89ec57f0e 100644 --- a/tutorial/quickstart.html +++ b/tutorial/quickstart.html @@ -4,6 +4,7 @@
- Tutorial
- API Guide
- Topics @@ -344,7 +345,7 @@ REST_FRAMEWORK = {
ModelSerializer class lets you automatically create a Serialize
Relational fields
When serializing model instances, there are a number of different ways you might choose to represent relationships. The default representation for ModelSerializer is to use the primary keys of the related instances.
Alternative representations include serializing using hyperlinks, serializing complete nested representations, or serializing with a custom representation.
-For full details see the serializer relations documentation.
+For full details see the serializer relations documentation.
HyperlinkedModelSerializer
The HyperlinkedModelSerializer class is similar to the ModelSerializer class except that it uses hyperlinks to represent relationships, rather than primary keys.
HTTP/1.1 420 Enhance Your Calm
Twitter API rate limiting response
-Throttling is similar to permissions, in that it determines if a request should be authorized. Throttles indicate a temporary state, and are used to control the rate of requests that clients can make to an API.
+Throttling is similar to permissions, in that it determines if a request should be authorized. Throttles indicate a temporary state, and are used to control the rate of requests that clients can make to an API.
As with permissions, multiple throttles may be used. Your API might have a restrictive throttle for unauthenticated requests, and a less restrictive throttle for authenticated requests.
Another scenario where you might want to use multiple throttles would be if you need to impose different constraints on different parts of the API, due to some services being particularly resource-intensive.
Multiple throttles can also be used if you want to impose both burst throttling rates, and sustained throttling rates. For example, you might want to limit a user to a maximum of 60 requests per minute, and 1000 requests per day.
diff --git a/api-guide/views.html b/api-guide/views.html index 11684c477..21c4ce4e1 100644 --- a/api-guide/views.html +++ b/api-guide/views.html @@ -4,6 +4,7 @@This view will use the default renderers, parsers, authentication classes etc specified in the settings.
+This view will use the default renderers, parsers, authentication classes etc specified in the settings.
API policy decorators
-To override the default settings, REST framework provides a set of additional decorators which can be added to your views. These must come after (below) the @api_view decorator. For example, to create a view that uses a throttle to ensure it can only be called once per day by a particular user, use the @throttle_classes decorator, passing a list of throttle classes:
To override the default settings, REST framework provides a set of additional decorators which can be added to your views. These must come after (below) the @api_view decorator. For example, to create a view that uses a throttle to ensure it can only be called once per day by a particular user, use the @throttle_classes decorator, passing a list of throttle classes:
from rest_framework.decorators import api_view, throttle_classes
from rest_framework.throttling import UserRateThrottle
diff --git a/api-guide/viewsets.html b/api-guide/viewsets.html
index 72cf2b23a..a9952205a 100644
--- a/api-guide/viewsets.html
+++ b/api-guide/viewsets.html
@@ -4,6 +4,7 @@
Django REST framework - ViewSets
+
@@ -41,8 +42,8 @@
GitHub
- Next
- Previous
+ Next
+ Previous
Search
@@ -56,56 +57,56 @@
Django REST framework - APIs made easy
+
@@ -41,7 +42,7 @@
GitHub
- Next
+ Next
Previous
Search
@@ -56,56 +57,56 @@
Some reasons you might want to use REST framework:
There is a live example API for testing purposes, available here.
@@ -317,57 +318,57 @@ urlpatterns = patterns('',
)
Quickstart
-Can't wait to get started? The quickstart guide is the fastest way to get up and running, and building APIs with REST framework.
+Can't wait to get started? The quickstart guide is the fastest way to get up and running, and building APIs with REST framework.
Tutorial
The tutorial will walk you through the building blocks that make up REST framework. It'll take a little while to get through, but it'll give you a comprehensive understanding of how everything fits together, and is highly recommended reading.
-
API Guide
The API guide is your complete reference manual to all the functionality provided by REST framework.
-
Topics
General guides to using REST framework.
-
Development
If you want to work on REST framework itself, clone the repository, then...
diff --git a/topics/2.2-announcement.html b/topics/2.2-announcement.html
index fbd04e29c..431177bc9 100644
--- a/topics/2.2-announcement.html
+++ b/topics/2.2-announcement.html
@@ -4,6 +4,7 @@
Django REST framework - REST framework 2.2 announcement
+
@@ -41,8 +42,8 @@
GitHub
- Next
- Previous
+ Next
+ Previous
Search
@@ -56,56 +57,56 @@
Django REST framework - REST framework 2.3 announcement
+
@@ -41,8 +42,8 @@
GitHub
- Next
- Previous
+ Next
+ Previous
Search
@@ -56,56 +57,56 @@
REST framework 2.3 announcement
REST framework 2.3 makes it even quicker and easier to build your Web APIs.
ViewSets and Routers
-The 2.3 release introduces the ViewSet and Router classes.
+The 2.3 release introduces the ViewSet and Router classes.
A viewset is simply a type of class based view that allows you to group multiple views into a single common class.
Routers allow you to automatically determine the URLconf for your viewset classes.
As an example of just how simple REST framework APIs can now be, here's an API written in a single urls.py module:
@@ -250,7 +251,7 @@ urlpatterns = patterns('',
url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
)
-The best place to get started with ViewSets and Routers is to take a look at the newest section in the tutorial, which demonstrates their usage.
+The best place to get started with ViewSets and Routers is to take a look at the newest section in the tutorial, which demonstrates their usage.
Simpler views
This release rationalises the API and implementation of the generic views, dropping the dependency on Django's SingleObjectMixin and MultipleObjectMixin classes, removing a number of unneeded attributes, and generally making the implementation more obvious and easy to work with.
This improvement is reflected in improved documentation for the GenericAPIView base class, and should make it easier to determine how to override methods on the base class if you need to write customized subclasses.
diff --git a/topics/ajax-csrf-cors.html b/topics/ajax-csrf-cors.html
index 47a73333d..0c90d60cb 100644
--- a/topics/ajax-csrf-cors.html
+++ b/topics/ajax-csrf-cors.html
@@ -4,6 +4,7 @@
Django REST framework - Working with AJAX, CSRF & CORS
+
@@ -41,8 +42,8 @@
GitHub
- Next
- Previous
+ Next
+ Previous
Search
@@ -56,56 +57,56 @@
Django REST framework - The Browsable API
+
@@ -41,8 +42,8 @@
GitHub
- Next
- Previous
+ Next
+ Previous
Search
@@ -56,56 +57,56 @@
API may stand for Application Programming Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the HTML format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using POST, PUT, and DELETE.
URLs
-If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The rest_framework package includes a reverse helper for this purpose.
+If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The rest_framework package includes a reverse helper for this purpose.
Formats
By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using ?format= in the request, so you can look at the raw JSON response in a browser by adding ?format=json to the URL. There are helpful extensions for viewing JSON in Firefox and Chrome.
Customizing
diff --git a/topics/browser-enhancements.html b/topics/browser-enhancements.html
index 7f71b9320..118d290cb 100644
--- a/topics/browser-enhancements.html
+++ b/topics/browser-enhancements.html
@@ -4,6 +4,7 @@
Django REST framework - Browser enhancements
+
@@ -41,8 +42,8 @@
GitHub
- Next
- Previous
+ Next
+ Previous
Search
@@ -56,56 +57,56 @@
Django REST framework - Contributing to REST framework
+
@@ -41,8 +42,8 @@
diff --git a/tutorial/6-viewsets-and-routers.html b/tutorial/6-viewsets-and-routers.html
index 353a8b627..6dd440291 100644
--- a/tutorial/6-viewsets-and-routers.html
+++ b/tutorial/6-viewsets-and-routers.html
@@ -4,6 +4,7 @@
Django REST framework - Tutorial 6: ViewSets & Routers
+
@@ -41,8 +42,8 @@
GitHub
- Next
- Previous
+ Next
+ Previous
Search
@@ -56,56 +57,56 @@
Django REST framework - Quickstart
+
@@ -41,8 +42,8 @@
GitHub
- Next
- Previous
+ Next
+ Previous
Search
@@ -56,56 +57,56 @@
Or directly through the browser...
Great, that was easy!
-If you want to get a more in depth understanding of how REST framework fits together head on over to the tutorial, or start browsing the API guide.
+If you want to get a more in depth understanding of how REST framework fits together head on over to the tutorial, or start browsing the API guide.