From 007855ec76233f3b54008600b58fc5e13c6fd495 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henryk=20Pl=C3=B6tz?= Date: Fri, 31 Jul 2020 11:00:47 +0200 Subject: [PATCH] Add overview of three different ways to restrict access --- docs/api-guide/permissions.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md index 32ecfaf46..f50c7e3c5 100644 --- a/docs/api-guide/permissions.md +++ b/docs/api-guide/permissions.md @@ -280,6 +280,30 @@ Note that the generic views will check the appropriate object level permissions, 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][filtering] for more details. +# Overview of access restriction methods + +REST framework offers three different methods to customize access restrictions on a case-by-case basis. These apply in different scenarios and have different effects and limitations. + + * `queryset`/`get_queryset()`: Limits the general visibility of existing objects from the database. The queryset limits which objects will be listed and which objects can be modified or deleted. The `get_queryset()` method can apply different querysets based on the current action. + * `permission_classes`/`get_permissions()`: General permission checks based on the current action, request and targeted object. Object level permissions can only be applied to retrieve, modify and deletion actions. Permission checks for list and create will be applied to the entire object type. (In case of list: subject to restrictions in the queryset.) + * `serializer_class`/`get_serializer()`: Instance level restrictions that apply to all objects on input and output. The serializer may have access to the request context. The `get_serializer()` method can apply different serializers based on the current action. + +The following table lists the access restriction methods and the level of control they offer over which actions. + +| | `queryset` | `permission_classes` | `serializer_class` | +|------------------------------------|------------|----------------------|--------------------| +| Action: list | global | no | object-level* | +| Action: create | no | global | object-level | +| Action: retrieve | global | object-level | object-level | +| Action: update | global | object-level | object-level | +| Action: partial_update | global | object-level | object-level | +| Action: destroy | global | object-level | no | +| Can reference action in decision | no** | yes | no** | +| Can reference request in decision | no** | yes | yes | + + \* A Serializer class should not raise PermissionDenied in a list action, or the entire list would not be returned.
+ \** The `get_*()` methods have access to the current view and can return different Serializer or QuerySet instances based on the request or action. + --- # Third party packages