diff --git a/docs/api-guide/routers.md b/docs/api-guide/routers.md
index 865829057..f196dc3cd 100644
--- a/docs/api-guide/routers.md
+++ b/docs/api-guide/routers.md
@@ -35,12 +35,12 @@ The example above would generate the following URL patterns:
* URL pattern: `^accounts/$` Name: `'account-list'`
* URL pattern: `^accounts/{pk}/$` Name: `'account-detail'`
-### Extra link and actions
+### Registering additional routes
-Any methods on the viewset decorated with `@link` or `@action` will also be routed.
+Any methods on the viewset decorated with `@detail_route` or `@list_route` will also be routed.
For example, a given method like this on the `UserViewSet` class:
- @action(permission_classes=[IsAdminOrIsSelf])
+ @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf])
def set_password(self, request, pk=None):
...
@@ -52,7 +52,7 @@ The following URL pattern would additionally be generated:
## SimpleRouter
-This router includes routes for the standard set of `list`, `create`, `retrieve`, `update`, `partial_update` and `destroy` actions. The viewset can also mark additional methods to be routed, using the `@link` or `@action` decorators.
+This router includes routes for the standard set of `list`, `create`, `retrieve`, `update`, `partial_update` and `destroy` actions. The viewset can also mark additional methods to be routed, using the `@detail_route` or `@list_route` decorators.
URL Style | HTTP Method | Action | URL Name |
@@ -62,8 +62,8 @@ This router includes routes for the standard set of `list`, `create`, `retrieve`
PUT | update |
PATCH | partial_update |
DELETE | destroy |
- {prefix}/{lookup}/{methodname}/ | GET | @link decorated method | {basename}-{methodname} |
- POST | @action decorated method |
+ {prefix}/{lookup}/{methodname}/ | GET | @detail_route decorated method | {basename}-{methodname} |
+ POST | @detail_route decorated method |
By default the URLs created by `SimpleRouter` are appending with a trailing slash.
@@ -86,8 +86,8 @@ This router is similar to `SimpleRouter` as above, but additionally includes a d
PUT | update |
PATCH | partial_update |
DELETE | destroy |
- {prefix}/{lookup}/{methodname}/[.format] | GET | @link decorated method | {basename}-{methodname} |
- POST | @action decorated method |
+ {prefix}/{lookup}/{methodname}/[.format] | GET | @detail_route decorated method | {basename}-{methodname} |
+ POST | @detail_route decorated method |
As with `SimpleRouter` the trailing slashs on the URL routes can be removed by setting the `trailing_slash` argument to `False` when instantiating the router.
diff --git a/docs/api-guide/viewsets.md b/docs/api-guide/viewsets.md
index 6d6bb1334..7a8d5979b 100644
--- a/docs/api-guide/viewsets.md
+++ b/docs/api-guide/viewsets.md
@@ -92,15 +92,15 @@ The default routers included with REST framework will provide routes for a stand
def destroy(self, request, pk=None):
pass
-If you have ad-hoc methods that you need to be routed to, you can mark them as requiring routing using the `@link`, `@action`, `@list_link`, or `@list_action` decorators. The `@link` and `@list_link` decorators will route `GET` requests, and the `@action` and `@list_action` decorators will route `POST` requests.
+If you have ad-hoc methods that you need to be routed to, you can mark them as requiring routing using the `@detail_route` or `@list_route` decorators.
-The `@link` and `@action` decorators contain `pk` in their URL pattern and are intended for methods which require a single instance. The `@list_link` and `@list_action` decorators are intended for methods which operate on a list of objects.
+The `@detail_route` decorator contains `pk` in its URL pattern and is intended for methods which require a single instance. The `@list_route` decorator is intended for methods which operate on a list of objects.
For example:
from django.contrib.auth.models import User
from rest_framework import viewsets
- from rest_framework.decorators import action, list_link
+ from rest_framework.decorators import detail_route, list_route
from rest_framework.response import Response
from myapp.serializers import UserSerializer, PasswordSerializer
@@ -111,7 +111,7 @@ For example:
queryset = User.objects.all()
serializer_class = UserSerializer
- @action()
+ @detail_route(methods=['post'])
def set_password(self, request, pk=None):
user = self.get_object()
serializer = PasswordSerializer(data=request.DATA)
@@ -123,7 +123,7 @@ For example:
return Response(serializer.errors,
status=status.HTTP_400_BAD_REQUEST)
- @list_link()
+ @list_route()
def recent_users(self, request):
recent_users = User.objects.all().order('-last_login')
page = self.paginate_queryset(recent_users)
@@ -132,13 +132,13 @@ For example:
The decorators can additionally take extra arguments that will be set for the routed view only. For example...
- @action(permission_classes=[IsAdminOrIsSelf])
+ @detail_route(methods=['post'], permission_classes=[IsAdminOrIsSelf])
def set_password(self, request, pk=None):
...
-The `@action` and `@list_action` decorators will route `POST` requests by default, but may also accept other HTTP methods, by using the `methods` argument. For example:
+By default, the decorators will route `GET` requests, but may also accept other HTTP methods, by using the `methods` argument. For example:
- @action(methods=['POST', 'DELETE'])
+ @detail_route(methods=['post', 'delete'])
def unset_password(self, request, pk=None):
...
---
diff --git a/docs/tutorial/6-viewsets-and-routers.md b/docs/tutorial/6-viewsets-and-routers.md
index f16add39d..f126ba045 100644
--- a/docs/tutorial/6-viewsets-and-routers.md
+++ b/docs/tutorial/6-viewsets-and-routers.md
@@ -25,7 +25,7 @@ Here we've used `ReadOnlyModelViewSet` class to automatically provide the defaul
Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighlight` view classes. We can remove the three views, and again replace them with a single class.
- from rest_framework.decorators import link
+ from rest_framework.decorators import detail_route
class SnippetViewSet(viewsets.ModelViewSet):
"""
@@ -39,7 +39,7 @@ Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighl
permission_classes = (permissions.IsAuthenticatedOrReadOnly,
IsOwnerOrReadOnly,)
- @link(renderer_classes=[renderers.StaticHTMLRenderer])
+ @detail_route(renderer_classes=[renderers.StaticHTMLRenderer])
def highlight(self, request, *args, **kwargs):
snippet = self.get_object()
return Response(snippet.highlighted)
@@ -49,9 +49,9 @@ Next we're going to replace the `SnippetList`, `SnippetDetail` and `SnippetHighl
This time we've used the `ModelViewSet` class in order to get the complete set of default read and write operations.
-Notice that we've also used the `@link` decorator to create a custom action, named `highlight`. This decorator can be used to add any custom endpoints that don't fit into the standard `create`/`update`/`delete` style.
+Notice that we've also used the `@detail_route` decorator to create a custom action, named `highlight`. This decorator can be used to add any custom endpoints that don't fit into the standard `create`/`update`/`delete` style.
-Custom actions which use the `@link` decorator will respond to `GET` requests. We could have instead used the `@action` decorator if we wanted an action that responded to `POST` requests.
+Custom actions which use the `@detail_route` decorator will respond to `GET` requests. We can use the `methods` argument if we wanted an action that responded to `POST` requests.
## Binding ViewSets to URLs explicitly
diff --git a/rest_framework/decorators.py b/rest_framework/decorators.py
index 92f551db7..1ca176f2c 100644
--- a/rest_framework/decorators.py
+++ b/rest_framework/decorators.py
@@ -3,13 +3,14 @@ The most important decorator in this module is `@api_view`, which is used
for writing function-based views with REST framework.
There are also various decorators for setting the API policies on function
-based views, as well as the `@action` and `@link` decorators, which are
+based views, as well as the `@detail_route` and `@list_route` decorators, which are
used to annotate methods on viewsets that should be included by routers.
"""
from __future__ import unicode_literals
from rest_framework.compat import six
from rest_framework.views import APIView
import types
+import warnings
def api_view(http_method_names):
@@ -111,6 +112,8 @@ def link(**kwargs):
"""
Used to mark a method on a ViewSet that should be routed for detail GET requests.
"""
+ msg = 'link is pending deprecation. Use detail_route instead.'
+ warnings.warn(msg, PendingDeprecationWarning, stacklevel=2)
def decorator(func):
func.bind_to_methods = ['get']
func.detail = True
@@ -123,6 +126,8 @@ def action(methods=['post'], **kwargs):
"""
Used to mark a method on a ViewSet that should be routed for detail POST requests.
"""
+ msg = 'action is pending deprecation. Use detail_route instead.'
+ warnings.warn(msg, PendingDeprecationWarning, stacklevel=2)
def decorator(func):
func.bind_to_methods = methods
func.detail = True
@@ -131,21 +136,21 @@ def action(methods=['post'], **kwargs):
return decorator
-def list_link(**kwargs):
+def detail_route(methods=['get'], **kwargs):
"""
- Used to mark a method on a ViewSet that should be routed for GET requests.
+ Used to mark a method on a ViewSet that should be routed for detail requests.
"""
def decorator(func):
- func.bind_to_methods = ['get']
- func.detail = False
+ func.bind_to_methods = methods
+ func.detail = True
func.kwargs = kwargs
return func
return decorator
-def list_action(methods=['post'], **kwargs):
+def list_route(methods=['get'], **kwargs):
"""
- Used to mark a method on a ViewSet that should be routed for POST requests.
+ Used to mark a method on a ViewSet that should be routed for list requests.
"""
def decorator(func):
func.bind_to_methods = methods
diff --git a/rest_framework/routers.py b/rest_framework/routers.py
index b8f19b66a..b761ba9ae 100644
--- a/rest_framework/routers.py
+++ b/rest_framework/routers.py
@@ -91,7 +91,7 @@ class SimpleRouter(BaseRouter):
initkwargs={'suffix': 'List'}
),
# Dynamically generated list routes.
- # Generated using @list_action or @list_link decorators
+ # Generated using @list_route decorator
# on methods of the viewset.
DynamicListRoute(
url=r'^{prefix}/{methodname}{trailing_slash}$',
@@ -111,7 +111,7 @@ class SimpleRouter(BaseRouter):
initkwargs={'suffix': 'Instance'}
),
# Dynamically generated detail routes.
- # Generated using @action or @link decorators on methods of the viewset.
+ # Generated using @detail_route decorator on methods of the viewset.
DynamicDetailRoute(
url=r'^{prefix}/{lookup}/{methodname}{trailing_slash}$',
name='{basename}-{methodnamehyphen}',
@@ -148,7 +148,7 @@ class SimpleRouter(BaseRouter):
known_actions = flatten([route.mapping.values() for route in self.routes if isinstance(route, Route)])
- # Determine any `@action` or `@link` decorated methods on the viewset
+ # Determine any `@detail_route` or `@list_route` decorated methods on the viewset
detail_routes = []
list_routes = []
for methodname in dir(viewset):
@@ -157,8 +157,8 @@ class SimpleRouter(BaseRouter):
detail = getattr(attr, 'detail', True)
if httpmethods:
if methodname in known_actions:
- raise ImproperlyConfigured('Cannot use @action, @link, @list_action '
- 'or @list_link decorator on method "%s" '
+ raise ImproperlyConfigured('Cannot use @detail_route or @list_route '
+ 'decorators on method "%s" '
'as it is an existing route' % methodname)
httpmethods = [method.lower() for method in httpmethods]
if detail:
@@ -169,7 +169,7 @@ class SimpleRouter(BaseRouter):
ret = []
for route in self.routes:
if isinstance(route, DynamicDetailRoute):
- # Dynamic detail routes (@link or @action decorator)
+ # Dynamic detail routes (@detail_route decorator)
for httpmethods, methodname in detail_routes:
initkwargs = route.initkwargs.copy()
initkwargs.update(getattr(viewset, methodname).kwargs)
@@ -180,7 +180,7 @@ class SimpleRouter(BaseRouter):
initkwargs=initkwargs,
))
elif isinstance(route, DynamicListRoute):
- # Dynamic list routes (@list_link or @list_action decorator)
+ # Dynamic list routes (@list_route decorator)
for httpmethods, methodname in list_routes:
initkwargs = route.initkwargs.copy()
initkwargs.update(getattr(viewset, methodname).kwargs)
diff --git a/rest_framework/tests/test_routers.py b/rest_framework/tests/test_routers.py
index 393101763..c3597e389 100644
--- a/rest_framework/tests/test_routers.py
+++ b/rest_framework/tests/test_routers.py
@@ -4,7 +4,7 @@ from django.test import TestCase
from django.core.exceptions import ImproperlyConfigured
from rest_framework import serializers, viewsets, permissions
from rest_framework.compat import include, patterns, url
-from rest_framework.decorators import link, action, list_link, list_action
+from rest_framework.decorators import detail_route, list_route
from rest_framework.response import Response
from rest_framework.routers import SimpleRouter, DefaultRouter
from rest_framework.test import APIRequestFactory
@@ -18,23 +18,23 @@ class BasicViewSet(viewsets.ViewSet):
def list(self, request, *args, **kwargs):
return Response({'method': 'list'})
- @action()
+ @detail_route(methods=['post'])
def action1(self, request, *args, **kwargs):
return Response({'method': 'action1'})
- @action()
+ @detail_route(methods=['post'])
def action2(self, request, *args, **kwargs):
return Response({'method': 'action2'})
- @action(methods=['post', 'delete'])
+ @detail_route(methods=['post', 'delete'])
def action3(self, request, *args, **kwargs):
return Response({'method': 'action2'})
- @link()
+ @detail_route()
def link1(self, request, *args, **kwargs):
return Response({'method': 'link1'})
- @link()
+ @detail_route()
def link2(self, request, *args, **kwargs):
return Response({'method': 'link2'})
@@ -175,7 +175,7 @@ class TestActionKeywordArgs(TestCase):
class TestViewSet(viewsets.ModelViewSet):
permission_classes = []
- @action(permission_classes=[permissions.AllowAny])
+ @detail_route(methods=['post'], permission_classes=[permissions.AllowAny])
def custom(self, request, *args, **kwargs):
return Response({
'permission_classes': self.permission_classes
@@ -196,14 +196,14 @@ class TestActionKeywordArgs(TestCase):
class TestActionAppliedToExistingRoute(TestCase):
"""
- Ensure `@action` decorator raises an except when applied
+ Ensure `@detail_route` decorator raises an except when applied
to an existing route
"""
def test_exception_raised_when_action_applied_to_existing_route(self):
class TestViewSet(viewsets.ModelViewSet):
- @action()
+ @detail_route(methods=['post'])
def retrieve(self, request, *args, **kwargs):
return Response({
'hello': 'world'
@@ -220,20 +220,20 @@ class DynamicListAndDetailViewSet(viewsets.ViewSet):
def list(self, request, *args, **kwargs):
return Response({'method': 'list'})
- @list_action()
- def list_action(self, request, *args, **kwargs):
+ @list_route(methods=['post'])
+ def list_route_post(self, request, *args, **kwargs):
return Response({'method': 'action1'})
- @action()
- def detail_action(self, request, *args, **kwargs):
+ @detail_route(methods=['post'])
+ def detail_route_post(self, request, *args, **kwargs):
return Response({'method': 'action2'})
- @list_link()
- def list_link(self, request, *args, **kwargs):
+ @list_route()
+ def list_route_get(self, request, *args, **kwargs):
return Response({'method': 'link1'})
- @link()
- def detail_link(self, request, *args, **kwargs):
+ @detail_route()
+ def detail_route_get(self, request, *args, **kwargs):
return Response({'method': 'link2'})
@@ -241,11 +241,11 @@ class TestDynamicListAndDetailRouter(TestCase):
def setUp(self):
self.router = SimpleRouter()
- def test_link_and_action_decorator(self):
+ def test_list_and_detail_route_decorators(self):
routes = self.router.get_routes(DynamicListAndDetailViewSet)
decorator_routes = [r for r in routes if not (r.name.endswith('-list') or r.name.endswith('-detail'))]
# Make sure all these endpoints exist and none have been clobbered
- for i, endpoint in enumerate(['list_action', 'list_link', 'detail_action', 'detail_link']):
+ for i, endpoint in enumerate(['list_route_get', 'list_route_post', 'detail_route_get', 'detail_route_post']):
route = decorator_routes[i]
# check url listing
if endpoint.startswith('list_'):
@@ -255,7 +255,7 @@ class TestDynamicListAndDetailRouter(TestCase):
self.assertEqual(route.url,
'^{{prefix}}/{{lookup}}/{0}{{trailing_slash}}$'.format(endpoint))
# check method to function mapping
- if endpoint.endswith('action'):
+ if endpoint.endswith('_post'):
method_map = 'post'
else:
method_map = 'get'