If no class authenticates, request.user will be set to an instance of django.contrib.auth.models.AnonymousUser, and request.auth will be set to None.
The value of request.user and request.auth for unauthenticated requests can be modified using the UNAUTHENTICATED_USER and UNAUTHENTICATED_TOKEN settings.
The default authentication schemes may be set globally, using the DEFAULT_AUTHENTICATION setting. For example.
The default authentication schemes may be set globally, using the DEFAULT_AUTHENTICATION_CLASSES setting. For example.
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'rest_framework.authentication.BasicAuthentication',
@@ -672,7 +672,7 @@ python manage.py createsuperuser
'provider.oauth2',
)
Then add OAuth2Authentication to your global DEFAULT_AUTHENTICATION setting:
Then add OAuth2Authentication to your global DEFAULT_AUTHENTICATION_CLASSES setting:
'DEFAULT_AUTHENTICATION_CLASSES': (
'rest_framework.authentication.OAuth2Authentication',
),
diff --git a/api-guide/exceptions/index.html b/api-guide/exceptions/index.html
index a0734a14..f9403f1d 100644
--- a/api-guide/exceptions/index.html
+++ b/api-guide/exceptions/index.html
@@ -442,7 +442,7 @@
Django's PermissionDenied exception.
In each case, REST framework will return a response with an appropriate status code and content-type. The body of the response will include any additional details regarding the nature of the error.
-By default all error responses will include a key detail in the body of the response, but other keys may also be included.
+Most error responses will include a key detail in the body of the response.
For example, the following request:
DELETE http://api.example.com/foo/bar HTTP/1.1
Accept: application/json
@@ -454,6 +454,14 @@ Content-Length: 42
{"detail": "Method 'DELETE' not allowed."}
+Validation errors are handled slightly differently, and will include the field names as the keys in the response. If the validation error was not specific to a particular field then it will use the "non_field_errors" key, or whatever string value has been set for the NON_FIELD_ERRORS_KEY setting.
+Any example validation error might look like this:
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+Content-Length: 94
+
+{"amount": ["A valid integer is required."], "description": ["This field may not be blank."]}
+
Custom exception handling
You can implement custom exception handling by creating a handler function that converts exceptions raised in your API views into response objects. This allows you to control the style of error responses used by your API.
The function must take a single argument, which is the exception to be handled, and should either return a Response object, or return None if the exception cannot be handled. If the handler returns None then the exception will be re-raised and Django will return a standard HTTP 500 'server error' response.
diff --git a/api-guide/fields/index.html b/api-guide/fields/index.html
index aedc4ea1..9cac530a 100644
--- a/api-guide/fields/index.html
+++ b/api-guide/fields/index.html
@@ -595,6 +595,7 @@
required
Normally an error will be raised if a field is not supplied during deserialization.
Set to false if this field is not required to be present during deserialization.
+Setting this to False also allows the object attribute or dictionary key to be omitted from output when serializing the instance. If the key is not present it will simply not be included in the output representation.
Defaults to True.
allow_null
Normally an error will be raised if None is passed to a serializer field. Set this keyword argument to True if None should be considered a valid value.
@@ -879,7 +880,7 @@ class UserSerializer(serializers.ModelSerializer):
class ColorField(serializers.Field):
"""
- Color objects are serialized into "rgb(#, #, #)" notation.
+ Color objects are serialized into 'rgb(#, #, #)' notation.
"""
def to_representation(self, obj):
return "rgb(%d, %d, %d)" % (obj.red, obj.green, obj.blue)
diff --git a/api-guide/filtering/index.html b/api-guide/filtering/index.html
index 6a55b999..fa0a15f8 100644
--- a/api-guide/filtering/index.html
+++ b/api-guide/filtering/index.html
@@ -702,6 +702,7 @@ class ProductFilter(django_filters.FilterSet):
queryset = User.objects.all()
serializer_class = UserSerializer
filter_backends = (filters.OrderingFilter,)
+ ordering_fields = ('username', 'email')
ordering = ('username',)
The ordering attribute may be either a string or a list/tuple of strings.
The name of the kwarg used may be modified by using the FORMAT_SUFFIX_KWARG setting.
Also note that format_suffix_patterns does not support descending into include URL patterns.
i18n_patternsIf using the i18n_patterns function provided by Django, as well as format_suffix_patterns you should make sure that the i18n_patterns function is applied as the final, or outermost function. For example:
url patterns = [
+ …
+]
+
+urlpatterns = i18n_patterns(
+ format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
+)
+There seems to be a view among some of the Web community that filename extensions are not a RESTful pattern, and that HTTP Accept headers should always be used instead.
The mixin classes provide the actions that are used to provide the basic view behavior. Note that the mixin classes provide action methods rather than defining the handler methods, such as .get() and .post(), directly. This allows for more flexible composition of behavior.
The mixin classes can be imported from rest_framework.mixins.
Provides a .list(request, *args, **kwargs) method, that implements listing a queryset.
If the queryset is populated, this returns a 200 OK response, with a serialized representation of the queryset as the body of the response. The response data may optionally be paginated.
The following classes are the concrete generic views. If you're using generic views this is normally the level you'll be working at unless you need heavily customized behavior.
+The view classes can be imported from rest_framework.generics.
Used for create-only endpoints.
Provides a post method handler.
view_name - The view name that should be used as the target of the relationship. If you're using the standard router classes this will be a string with the format <model_name>-detail. required.lookup_field - The field on the target that should be used for the lookup. Should correspond to a URL keyword argument on the referenced view. Default is 'pk'.lookup_url_kwarg - The name of the keyword argument defined in the URL conf that corresponds to the lookup field. Defaults to using the same value as lookup_field.format - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the format argument.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.
include with routersThe .urls attribute on a router instance is simply a standard list of URL patterns. There are a number of different styles for how you can include these URLs.
For example, you can append router.urls to a list of existing views…
router = routers.SimpleRouter()
+router.register(r'users', UserViewSet)
+router.register(r'accounts', AccountViewSet)
+
+urlpatterns = [
+ url(r'^forgot-password/$, ForgotPasswordFormView.as_view(),
+]
+
+urlpatterns += router.urls
+Alternatively you can use Django's include function, like so…
urlpatterns = [
+ url(r'^forgot-password/$, ForgotPasswordFormView.as_view(),
+ url(r'^', include(router.urls))
+]
+Router URL patterns can also be namespaces.
+urlpatterns = [
+ url(r'^forgot-password/$, ForgotPasswordFormView.as_view(),
+ url(r'^api/', include(router.urls, namespace='api'))
+]
+If using namespacing with hyperlinked serializers you'll also need to ensure that any view_name parameters on the serializers correctly reflect the namespace. In the example above you'd need to include a parameter such as view_name='api:user-detail' for serializer fields hyperlinked to the user detail view.
Any methods on the viewset decorated with @detail_route or @list_route will also be routed.
For example, given a method like this on the UserViewSet class:
^users/{pk}/set_password/$ Name: 'user-set-password'If you do not want to use the default URL generated for your custom action, you can instead use the url_path parameter to customize it.
+For example, if you want to change the URL for our custom action to ^users/{pk}/change-password/$, you could write:
from myapp.permissions import IsAdminOrIsSelf
+from rest_framework.decorators import detail_route
+
+class UserViewSet(ModelViewSet):
+ ...
+
+ @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf], url_path='change-password')
+ def set_password(self, request, pk=None):
+ ...
+The above example would now generate the following URL pattern:
+^users/{pk}/change-password/$ Name: 'user-change-password'For more information see the viewset documentation on marking extra actions for routing.
For more details on this approach see the Django documentation on model managers, and this blogpost on using model and manger classes.
+For more details on this approach see the Django documentation on model managers, and this blogpost on using model and manager classes.
The Serializer class can also handle serializing or deserializing lists of objects.