13 KiB
Executable File
Generic views
Django’s generic views... were developed as a shortcut for common usage patterns... They take certain common idioms and patterns found in view development and abstract them so that you can quickly write common views of data without having to repeat yourself.
One of the key benefits of class based views is the way they allow you to compose bits of reusable behaviour. REST framework takes advantage of this by providing a number of pre-built views that provide for commonly used patterns.
The generic views provided by REST framework allow you to quickly build API views that map closely to your database models.
If the generic views don't suit the needs of your API, you can drop down to using the regular APIView
class, or reuse the mixins and base classes used by the generic views to compose your own set of reusable generic views.
Examples
Typically when using the generic views, you'll override the view, and set several class attributes.
class UserList(generics.ListCreateAPIView):
queryset = User.objects.all()
serializer_class = UserSerializer
permission_classes = (IsAdminUser,)
paginate_by = 100
For more complex cases you might also want to override various methods on the view class. For example.
class UserList(generics.ListCreateAPIView):
queryset = User.objects.all()
serializer_class = UserSerializer
permission_classes = (IsAdminUser,)
def get_paginate_by(self):
"""
Use smaller pagination for HTML representations.
"""
self.request.accepted_renderer.format == 'html':
return 20
return 100
For very simple cases you might want to pass through any class attributes using the .as_view()
method. For example, your URLconf might include something the following entry.
url(r'^/users/', ListCreateAPIView.as_view(model=User) name='user-list')
API Reference
GenericAPIView
This class extends REST framework's APIView
class, adding commonly required behavior for standard list and detail views.
Each of the concrete generic views provided is built by combining GenericAPIView
, with one or more mixin classes.
Attributes
Basic settings:
The following attributes control the basic view behavior.
queryset
- The queryset that should be used for returning objects from this view. Typically, you must either set this attribute, or override theget_queryset()
method.serializer_class
- The serializer class that should be used for validating and deserializing input, and for serializing output. Typically, you must either set this attribute, or override theget_serializer_class()
method.lookup_field
- The field that should be used to lookup individual model instances. Defaults to'pk'
. The URL conf should include a keyword argument corresponding to this value. More complex lookup styles can be supported by overriding theget_object()
method.
Pagination:
The following attibutes are used to control pagination when used with list views.
paginate_by
- The size of pages to use with paginated data. If set toNone
then pagination is turned off. If unset this uses the same value as thePAGINATE_BY
setting, which defaults toNone
.paginate_by_param
- The name of a query parameter, which can be used by the client to overide the default page size to use for pagination. If unset this uses the same value as thePAGINATE_BY_PARAM
setting, which defaults toNone
.pagination_serializer_class
- The pagination serializer class to use when determining the style of paginated responses. Defaults to the same value as theDEFAULT_PAGINATION_SERIALIZER_CLASS
setting.page_kwarg
- The name of a URL kwarg or URL query parameter which can be used by the client to control which page is requested. Defaults to'page'
.
Other:
filter_backend
- The filter backend class that should be used for filtering the queryset. Defaults to the same value as theFILTER_BACKEND
setting.allow_empty
- Determines if an empty list should successfully display zero results, or return a 404 response. Defaults toTrue
, meaning empty lists will return sucessful200 OK
responses, with zero results.model
- This shortcut may be used instead of setting either (or both) of thequeryset
/serializer_class
attributes, although using the explicit style is generally preferred. If used instead ofserializer_class
, then thenDEFAULT_MODEL_SERIALIZER_CLASS
setting will determine the base serializer class.
Methods
Base methods:
get_queryset(self)
Returns the queryset that should be used for list views, and that should be used as the base for lookups in detail views. Defaults to returning the queryset specified by the queryset
attribute, or the default queryset for the model if the model
shortcut is being used.
May be overridden to provide dynamic behavior such as returning a queryset that is specific to the user making the request.
For example:
def get_queryset(self):
return self.user.accounts.all()
get_object(self)
Returns an object instance that should be used for detail views. Defaults to using the lookup_field
parameter to filter the base queryset.
May be overridden to provide more complex behavior such as object lookups based on more than one URL kwarg.
For example:
def get_object(self):
queryset = self.get_queryset()
filter = {}
for field in self.multiple_lookup_fields:
filter[field] = self.kwargs[field]
return get_object_or_404(queryset, **filter)
get_serializer_class(self)
Returns the class that should be used for the serializer. Defaults to returning the serializer_class
attribute, or dynamically generating a serializer class if the model
shortcut is being used.
May be override to provide dynamic behavior such as using different serializers for read and write operations, or providing different serializers to different types of uesr.
For example:
def get_serializer_class(self):
if self.request.user.is_staff:
return FullAccountSerializer
return BasicAccountSerializer
get_paginate_by(self)
Returna the page size to use with pagination. By default this uses the paginate_by
attribute, and may be overridden by the cient if the paginate_by_param
attribute is set.
You may want to override this method to provide more complex behavior such as modifying page sizes based on the media type of the response.
For example:
def get_paginate_by(self):
self.request.accepted_renderer.format == 'html':
return 20
return 100
Save hooks:
The following methods are provided as placeholder interfaces. They contain empty implementations and are not called directly by GenericAPIView
, but they are overridden and used by some of the mixin classes.
pre_save(self, obj)
- A hook that is called before saving an object.post_save(self, obj, created=False)
- A hook that is called after saving an object.
Other methods:
You won't typically need to override the following methods, although you might need to call into them if you're writing custom views using GenericAPIView
.
get_serializer_context(self)
- Returns a dictionary containing any extra context that should be supplied to the serializer. Defaults to including'request'
,'view'
and'format'
keys.get_serializer(self, instance=None, data=None, files=None, many=False, partial=False)
- Returns a serializer instance.get_pagination_serializer(self, page)
- Returns a serializer instance to use with paginated data.paginate_queryset(self, queryset)
- Paginate a queryset if required, either returning a page object, orNone
if pagination is not configured for this view.filter_queryset(self, queryset)
- Given a queryset, filter it with whichever filter backend is in use, returning a new queryset.
Concrete View Classes
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.
CreateAPIView
Used for create-only endpoints.
Provides post
method handlers.
Extends: GenericAPIView, CreateModelMixin
ListAPIView
Used for read-only endpoints to represent a collection of model instances.
Provides a get
method handler.
Extends: GenericAPIView, ListModelMixin
RetrieveAPIView
Used for read-only endpoints to represent a single model instance.
Provides a get
method handler.
Extends: GenericAPIView, RetrieveModelMixin
DestroyAPIView
Used for delete-only endpoints for a single model instance.
Provides a delete
method handler.
Extends: GenericAPIView, DestroyModelMixin
UpdateAPIView
Used for update-only endpoints for a single model instance.
Provides put
and patch
method handlers.
Extends: GenericAPIView, UpdateModelMixin
ListCreateAPIView
Used for read-write endpoints to represent a collection of model instances.
Provides get
and post
method handlers.
Extends: GenericAPIView, ListModelMixin, CreateModelMixin
RetrieveUpdateAPIView
Used for read or update endpoints to represent a single model instance.
Provides get
, put
and patch
method handlers.
Extends: GenericAPIView, RetrieveModelMixin, UpdateModelMixin
RetrieveDestroyAPIView
Used for read or delete endpoints to represent a single model instance.
Provides get
and delete
method handlers.
Extends: GenericAPIView, RetrieveModelMixin, DestroyModelMixin
RetrieveUpdateDestroyAPIView
Used for read-write-delete endpoints to represent a single model instance.
Provides get
, put
, patch
and delete
method handlers.
Extends: GenericAPIView, RetrieveModelMixin, UpdateModelMixin, DestroyModelMixin
Mixins
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.
ListModelMixin
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.
If the queryset is empty this returns a 200 OK
response, unless the .allow_empty
attribute on the view is set to False
, in which case it will return a 404 Not Found
.
Should be mixed in with [MultipleObjectAPIView].
CreateModelMixin
Provides a .create(request, *args, **kwargs)
method, that implements creating and saving a new model instance.
If an object is created this returns a 201 Created
response, with a serialized representation of the object as the body of the response. If the representation contains a key named url
, then the Location
header of the response will be populated with that value.
If the request data provided for creating the object was invalid, a 400 Bad Request
response will be returned, with the error details as the body of the response.
Should be mixed in with any GenericAPIView.
RetrieveModelMixin
Provides a .retrieve(request, *args, **kwargs)
method, that implements returning an existing model instance in a response.
If an object can be retrieved this returns a 200 OK
response, with a serialized representation of the object as the body of the response. Otherwise it will return a 404 Not Found
.
Should be mixed in with [SingleObjectAPIView].
UpdateModelMixin
Provides a .update(request, *args, **kwargs)
method, that implements updating and saving an existing model instance.
Also provides a .partial_update(request, *args, **kwargs)
method, which is similar to the update
method, except that all fields for the update will be optional. This allows support for HTTP PATCH
requests.
If an object is updated this returns a 200 OK
response, with a serialized representation of the object as the body of the response.
If an object is created, for example when making a DELETE
request followed by a PUT
request to the same URL, this returns a 201 Created
response, with a serialized representation of the object as the body of the response.
If the request data provided for updating the object was invalid, a 400 Bad Request
response will be returned, with the error details as the body of the response.
Should be mixed in with [SingleObjectAPIView].
DestroyModelMixin
Provides a .destroy(request, *args, **kwargs)
method, that implements deletion of an existing model instance.
If an object is deleted this returns a 204 No Content
response, otherwise it will return a 404 Not Found
.
Should be mixed in with [SingleObjectAPIView].