diff --git a/api-guide/authentication.html b/api-guide/authentication.html index 9b11fbe5b..c05b60aa9 100644 --- a/api-guide/authentication.html +++ b/api-guide/authentication.html @@ -121,6 +121,7 @@ a.fusion-poweredby {
lookup_field
- The model field that should be used to for performing object lookup of individual model instances. Defaults to 'pk'
. Note that when using hyperlinked APIs you'll need to ensure that both the API views and the serializer classes set the lookup fields if you need to use a custom value.lookup_url_kwarg
- The URL keyword argument that should be used for object lookup. The URL conf should include a keyword argument corresponding to this value. If unset this defaults to using the same value as lookup_field
.Shortcuts:
-model
- This shortcut may be used instead of setting either (or both) of the queryset
/serializer_class
attributes, although using the explicit style is generally preferred. If used instead of serializer_class
, then DEFAULT_MODEL_SERIALIZER_CLASS
setting will determine the base serializer class. Note that model
is only ever used for generating a default queryset or serializer class - the queryset
and serializer_class
attributes are always preferred if provided.Pagination:
The following attributes are used to control pagination when used with list views.
filter_backends
- A list of filter backend classes that should be used for filtering the queryset. Defaults to the same value as the DEFAULT_FILTER_BACKENDS
setting.Deprecated attributes:
+model
- This shortcut may be used instead of setting either (or both) of the queryset
/serializer_class
attributes. The explicit style is preferred over the .model
shortcut, and usage of this attribute is now deprecated.Base methods:
get_queryset(self)
The IsAuthenticatedOrReadOnly
will allow authenticated users to perform any request. Requests for unauthorised users will only be permitted if the request method is one of the "safe" methods; GET
, HEAD
or OPTIONS
.
This permission is suitable if you want to your API to allow read permissions to anonymous users, and only allow write permissions to authenticated users.
This permission class ties into Django's standard django.contrib.auth
model permissions. When applied to a view that has a .model
property, authorization will only be granted if the user is authenticated and has the relevant model permissions assigned.
This permission class ties into Django's standard django.contrib.auth
model permissions. This permission must only be applied to views that has a .queryset
property set. Authorization will only be granted if the user is authenticated and has the relevant model permissions assigned.
POST
requests require the user to have the add
permission on the model.PUT
and PATCH
requests require the user to have the change
permission on the model.The default behaviour can also be overridden to support custom model permissions. For example, you might want to include a view
model permission for GET
requests.
To use custom model permissions, override DjangoModelPermissions
and set the .perms_map
property. Refer to the source code for details.
queryset
attribute.If you're using this permission with a view that uses an overridden get_queryset()
method there may not be a queryset
attribute on the view. In this case we suggest also marking the view with a sential queryset, so that this class can determine the required permissions. For example:
queryset = User.objects.none() # Required for DjangoModelPermissions
+
Similar to DjangoModelPermissions
, but also allows unauthenticated users to have read-only access to the API.
This permission class ties into Django's standard object permissions framework that allows per-object permissions on models. In order to use this permission class, you'll also need to add a permission backend that supports object-level permissions, such as django-guardian.
-When applied to a view that has a .model
property, authorization will only be granted if the user is authenticated and has the relevant per-object permissions and relevant model permissions assigned.
As with DjangoModelPermissions
, this permission must only be applied to views that have a .queryset
property. Authorization will only be granted if the user is authenticated and has the relevant per-object permissions and relevant model permissions assigned.
POST
requests require the user to have the add
permission on the model instance.PUT
and PATCH
requests require the user to have the change
permission on the model instance.Note: The base_name
argument is used to specify the initial part of the view name pattern. In the example above, that's the user
or account
part.
Typically you won't need to specify the base-name
argument, but if you have a viewset where you've defined a custom get_queryset
method, then the viewset may not have any .model
or .queryset
attribute set. If you try to register that viewset you'll see an error like this:
'base_name' argument not specified, and could not automatically determine the name from the viewset, as it does not have a '.model' or '.queryset' attribute.
+Typically you won't need to specify the base-name
argument, but if you have a viewset where you've defined a custom get_queryset
method, then the viewset may not have a .queryset
attribute set. If you try to register that viewset you'll see an error like this:
+'base_name' argument not specified, and could not automatically determine the name from the viewset, as it does not have a '.queryset' attribute.
This means you'll need to explicitly set the base_name
argument when registering the viewset, as it could not be automatically determined from the model name.
diff --git a/api-guide/serializers.html b/api-guide/serializers.html
index f90aff167..3a4f9875f 100644
--- a/api-guide/serializers.html
+++ b/api-guide/serializers.html
@@ -121,6 +121,7 @@ a.fusion-poweredby {
2.0 Announcement
2.2 Announcement
2.3 Announcement
+ 2.4 Announcement
Kickstarter Announcement
Release Notes
Credits
diff --git a/api-guide/settings.html b/api-guide/settings.html
index 598232632..4b4768516 100644
--- a/api-guide/settings.html
+++ b/api-guide/settings.html
@@ -121,6 +121,7 @@ a.fusion-poweredby {
2.0 Announcement
2.2 Announcement
2.3 Announcement
+ 2.4 Announcement
Kickstarter Announcement
Release Notes
Credits
@@ -275,9 +276,6 @@ print api_settings.DEFAULT_AUTHENTICATION_CLASSES
Generic view settings
The following settings control the behavior of the generic class based views.
-DEFAULT_MODEL_SERIALIZER_CLASS
-A class that determines the default type of model serializer that should be used by a generic view if model
is specified, but serializer_class
is not provided.
-Default: 'rest_framework.serializers.ModelSerializer'
DEFAULT_PAGINATION_SERIALIZER_CLASS
A class the determines the default serialization style for paginated responses.
Default: rest_framework.pagination.PaginationSerializer
diff --git a/api-guide/status-codes.html b/api-guide/status-codes.html
index 070d004fb..4df4bc0f7 100644
--- a/api-guide/status-codes.html
+++ b/api-guide/status-codes.html
@@ -121,6 +121,7 @@ a.fusion-poweredby {
2.0 Announcement
2.2 Announcement
2.3 Announcement
+ 2.4 Announcement
Kickstarter Announcement
Release Notes
Credits
diff --git a/api-guide/testing.html b/api-guide/testing.html
index c30b1e95a..4f23c943c 100644
--- a/api-guide/testing.html
+++ b/api-guide/testing.html
@@ -121,6 +121,7 @@ a.fusion-poweredby {
2.0 Announcement
2.2 Announcement
2.3 Announcement
+ 2.4 Announcement
Kickstarter Announcement
Release Notes
Credits
diff --git a/api-guide/throttling.html b/api-guide/throttling.html
index 496424816..71db0319d 100644
--- a/api-guide/throttling.html
+++ b/api-guide/throttling.html
@@ -121,6 +121,7 @@ a.fusion-poweredby {
2.0 Announcement
2.2 Announcement
2.3 Announcement
+ 2.4 Announcement
Kickstarter Announcement
Release Notes
Credits
diff --git a/api-guide/views.html b/api-guide/views.html
index 934c0aaef..0118412b1 100644
--- a/api-guide/views.html
+++ b/api-guide/views.html
@@ -121,6 +121,7 @@ a.fusion-poweredby {
2.0 Announcement
2.2 Announcement
2.3 Announcement
+ 2.4 Announcement
Kickstarter Announcement
Release Notes
Credits
diff --git a/api-guide/viewsets.html b/api-guide/viewsets.html
index 454d7d82f..2e5915a97 100644
--- a/api-guide/viewsets.html
+++ b/api-guide/viewsets.html
@@ -121,6 +121,7 @@ a.fusion-poweredby {
2.0 Announcement
2.2 Announcement
2.3 Announcement
+ 2.4 Announcement
Kickstarter Announcement
Release Notes
Credits
diff --git a/index.html b/index.html
index b7a5a2c2c..268773dbb 100644
--- a/index.html
+++ b/index.html
@@ -121,6 +121,7 @@ a.fusion-poweredby {
2.0 Announcement
2.2 Announcement
2.3 Announcement
+ 2.4 Announcement
Kickstarter Announcement
Release Notes
Credits
@@ -289,14 +290,9 @@ pip install django-filter # Filtering support
Note that the URL path can be whatever you want, but you must include 'rest_framework.urls'
with the 'rest_framework'
namespace.
Example
Let's take a look at a quick example of using REST framework to build a simple model-backed API.
-We'll create a read-write API for accessing users and groups.
+We'll create a read-write API for accessing information on the users of our project.
Any global settings for a REST framework API are kept in a single configuration dictionary named REST_FRAMEWORK
. Start off by adding the following to your settings.py
module:
REST_FRAMEWORK = {
- # Use hyperlinked styles by default.
- # Only used if the `serializer_class` attribute is not set on a view.
- 'DEFAULT_MODEL_SERIALIZER_CLASS':
- 'rest_framework.serializers.HyperlinkedModelSerializer',
-
# Use Django's standard `django.contrib.auth` permissions,
# or allow read-only access for unauthenticated users.
'DEFAULT_PERMISSION_CLASSES': [
@@ -307,33 +303,35 @@ pip install django-filter # Filtering support
Don't forget to make sure you've also added rest_framework
to your INSTALLED_APPS
.
We're ready to create our API now.
Here's our project's root urls.py
module:
-from django.conf.urls import url, patterns, include
-from django.contrib.auth.models import User, Group
-from rest_framework import viewsets, routers
+from django.conf.urls import url, include
+from django.contrib.auth.models import User
+from rest_framework import routers, serializers, viewsets
+
+# Serializers define the API representation.
+class UserSerializer(serializers.HyperlinkedModelSerializer):
+ class Meta:
+ model = User
+ fields = ('url', 'username', 'email', 'is_staff')
# ViewSets define the view behavior.
class UserViewSet(viewsets.ModelViewSet):
- model = User
-
-class GroupViewSet(viewsets.ModelViewSet):
- model = Group
-
+ queryset = User.objects.all()
+ serializer_class = UserSerializer
# Routers provide an easy way of automatically determining the URL conf.
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)
-router.register(r'groups', GroupViewSet)
-
# Wire up our API using automatic URL routing.
# Additionally, we include login URLs for the browseable API.
-urlpatterns = patterns('',
+urlpatterns = [
url(r'^', include(router.urls)),
url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
-)
+]
+You can now open the API in your browser at http://127.0.0.1:8000/, and view your new 'users' API. If you use the login control in the top right corner you'll also be able to add, create and delete users from the system.
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.
@@ -384,6 +382,7 @@ urlpatterns = patterns('',
- 2.0 Announcement
- 2.2 Announcement
- 2.3 Announcement
+- 2.4 Announcement
- Kickstarter Announcement
- Release Notes
- Credits
diff --git a/topics/2.2-announcement.html b/topics/2.2-announcement.html
index d78540e94..158c58d4f 100644
--- a/topics/2.2-announcement.html
+++ b/topics/2.2-announcement.html
@@ -121,6 +121,7 @@ a.fusion-poweredby {
- 2.0 Announcement
- 2.2 Announcement
- 2.3 Announcement
+ - 2.4 Announcement
- Kickstarter Announcement
- Release Notes
- Credits
diff --git a/topics/2.3-announcement.html b/topics/2.3-announcement.html
index be0f328c6..364483d86 100644
--- a/topics/2.3-announcement.html
+++ b/topics/2.3-announcement.html
@@ -57,7 +57,7 @@ a.fusion-poweredby {