This will obviously require more extensive testing and documentation updates, but I'd like to hammer out the implementation details first. But first, here's a preview of the changes to the browsable API:

The above changes include:

Breadcrumb and page title support custom names/titles for actions instead of just "User instance".
The method docstring is now used as the action's description.
A dropdown of "Extra Actions" (appropriately filtered to detail/non-detail actions).
Also, note that custom serializer classes were already supported.

To implement this, it was necessary to change how routers and viewsets interact. At a higher level:

Views more explicitly customize their display name and description.
ViewSets are provided more context/configuration from the router. For example, it can now determine if the current request is operation on a list or detail action.

In more detail detail:

Note that these changes build off ofAdd '.basename' and '.reverse_action()' to ViewSet #5648 andRework dynamic list/detail actions #5705, which were spun out of this PR.
Views now acceptname anddescription via theinitkwargs.
- This provides a general hook for customizing their display on the browsable API.
- This is necessary to allow action methods to specify they're own name/description.
get_view_name andget_view_description now expect the View instance instead of a class.
get_view_name andget_view_description respect the new Viewname anddescription.
ViewSets considername andsuffix to be mutually exclusive.
Theaction decorator now allows users to specify thename, uses the docstring as the description.
AddsViewSet.get_extra_action_url_map for rendering extra actions.
Adds renderer/template code for both the browsable and admin APIs.

Adds method mapping to ViewSet actions. Multiple ViewSet methods can handle different HTTP methods of an action. ex:

classMyViewSet(ViewSet):@action(detail=False)defexample(self,request,**kwargs):        ...@example.mapping.postdefcreate_example(self,request,**kwargs):        ...

TODO:

Look into:Mark extra actions which corresponds to the same URL #4920,~~AutoSchema fails when set on detail_route #5630~~
Add tests for new functionality
Add actions list to browsable API
Add actions list to admin API
Fix action title/description display in browsable API
Update docs, changelog
~~Rename/deprecatebase_name tobasename for consistency.~~

rpkilby added this to thev3.8 milestone

Nov 17, 2017

rpkilby force-pushed theviewset-actions branch 2 times, most recently from27a2e93 to7bac555Compare

November 18, 2017 02:39

auvipy reviewed

Nov 18, 2017

View reviewed changes

Copy link

Collaborator

auvipy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I like the naming of action rater then detail/list route.

how many routable actions will be possible on a single viewset?

Copy link

ContributorAuthor

rpkilby commentedNov 18, 2017

I like the naming of action rater then detail/list route.

Agreed@auvipy. It's not so much that I'm in favor ofaction, more that I've never particularly likedlist_route/detail_route.

how many routable actions will be possible on a single viewset?

There isn't any limit, as there wasn't any limit to list/detail routes.

SIde note: more commits incoming

rpkilby force-pushed theviewset-actions branch from6ef27c6 toeafe0ccCompare

November 18, 2017 05:14

Copy link

Collaborator

auvipy commentedNov 18, 2017

It would be great to see some good example as part of this pr. thanks for the great work!

Copy link

ContributorAuthor

rpkilby commentedNov 18, 2017

@auvipy, right now, there's a screenshot in the original comment, which should demonstrate the practical changes to the browsable API. As far as code goes, it's pretty much just:

classMyViewSet(...):@action(methods=['get'],detail=True,name='Custom name'serializer_class=ThingySerializer)defdo_a_thing(self,request,pk,*args,**kwargs):"""        # Docstrings are now used as descriptions!        """

rpkilby mentioned this pull request

Nov 18, 2017

Support "extra actions" for routing in the HTML forms for the browsable API#2062

Closed

Copy link

Collaborator

auvipy commentedNov 18, 2017

How this change would affect this#5551?

Copy link

ContributorAuthor

rpkilby commentedNov 18, 2017

These changes aren't directly related to#5551.

merwok reviewed

Nov 18, 2017

View reviewed changes

rest_framework/decorators.py Outdated

		warnings.warn(
		"`detail_route` has been deprecated in favor of `action`, which accepts a "
		"`detail` boolean. Use `@action(['GET'], detail=True)` instead.",
		PendingDeprecationWarning

Copy link

Contributor

merwokNov 18, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I think this needs astacklevel parameter so that the source code in the traceback points to the file using detail_route, not this file.

carltongibson added the Needs further review label

Nov 20, 2017

carltongibson reviewed

Nov 20, 2017

View reviewed changes

Copy link

Collaborator

carltongibson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

OK. Interesting.

Initial thought is 😱 breaking change but with the deprecation it's not a big issue I think.

I need to sit down with the implementation details but cool. 👍

rest_framework/decorators.py Outdated

		Used to mark a method on a ViewSet that should be routed for detail requests.
		"""
		warnings.warn(
		"`detail_route` has been deprecated in favor of `action`, which accepts a "

Copy link

Collaborator

carltongibsonNov 20, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

This is quite a big change for users. I think I'd like to see the message here saying, "pending deprecation" and "will be removed in 3.10" so that it's mega-clear what sort of timescale users have.

This will require updating these messages for 3.9 (unless we're clever with the wording) but I think we need to be extra helpful here.
I think this also merits a beginning on the release notes.

Copy link

ContributorAuthor

rpkilbyNov 21, 2017•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Agreed. My main consideration right now is to determine if this is the path we ultimately want to move toward, and then work backwards from that w/ deprecations and whatnot.

Right now, the state of the PR is more exploratory. For example, I also want to try and fix#4920, which will require more modifications to the dynamic route generation.

rpkilby mentioned this pull request

Dec 4, 2017

Add '.basename' and '.reverse_action()' to ViewSet#5648

Merged

rpkilby force-pushed theviewset-actions branch froma8dff35 toc028686Compare

December 4, 2017 11:15

rpkilby mentioned this pull request

Dec 22, 2017

Rework dynamic list/detail actions#5705

Merged

3 tasks

carltongibson reviewed

Jan 19, 2018

View reviewed changes

Copy link

Collaborator

carltongibson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Hey@rpkilby. This is pay off from#5705. Fancy re-doing from that as a base? (If it's not too much faff.)

carltongibson added Enhancement and removed Needs further review labels

Jan 19, 2018

rpkilby force-pushed theviewset-actions branch fromc028686 to5207a3fCompare

January 25, 2018 13:21

Copy link

Collaborator

carltongibson commentedMar 26, 2018

Hey@rpkilby. Any appetite for pushing this over the line? It looks like it just needs docs and a few test cases

carltongibson removed this from the3.8 Release milestone

Apr 3, 2018

rpkilby force-pushed theviewset-actions branch 2 times, most recently from144c55d tob4d3eabCompare

May 16, 2018 09:26

rpkilby changed the title~~[wip] Viewset extra actions~~Improvements to ViewSet extra actions

May 16, 2018

rpkilby added this to the3.9 Release milestone

May 16, 2018

rpkilby mentioned this pull request

May 16, 2018

Mark extra actions which corresponds to the same URL#4920

Closed

Copy link

ContributorAuthor

rpkilby commentedMay 16, 2018

Hi all - the PR is largely done and ready for review (documentation not withstanding). In addition to tests, the updates implements#4920 and copies the "Extra Actions" dropdown from the Browsable API to the Admin API template.

rpkilby force-pushed theviewset-actions branch from98397c9 to4bb5de5Compare

May 16, 2018 14:16

carltongibson reviewed

Jun 22, 2018

View reviewed changes

Copy link

Collaborator

carltongibson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Hey@rpkilby.

Sorry for the slow review here.

Great stuff.

I'm expecting to see some docs here. 🙂

View suffix already set by initializer

06265b6

rpkilby force-pushed theviewset-actions branch from4bb5de5 to90ae57cCompare

June 24, 2018 22:00

Add 'name' and 'description' attributes to ViewSet

d0af8e8

ViewSets may now provide their `name` and `description` attributesdirectly, instead of relying on view introspection to derive them.These attributes may also be provided with the view's initkwargs.The ViewSet `name` and `suffix` initkwargs are mutually exclusive.The `action` decorator now provides the `name` and `description` tothe view's initkwargs. By default, these values are derived from themethod name and its docstring. The `name` may be overridden by providingit as an argument to the decorator.The `get_view_name` and `get_view_description` hooks now provide theview instance to the handler, instead of the view class. The defaultimplementations of these handlers now respect the `name`/`description`.

rpkilby force-pushed theviewset-actions branch 4 times, most recently from597415d toc604380Compare

June 25, 2018 17:29

Ryan P Kilby added2 commits

June 25, 2018 13:39

Add 'extra actions' to ViewSet & browsable APIs

3c60b4b

Update simple router tests

9b64818

Removed old test logic around link/action decorators from `v2.3`. Alsosimplified the test by making the results explicit instead of computed.

rpkilby force-pushed theviewset-actions branch fromc604380 todeb0477Compare

June 25, 2018 17:40

Add method mapping to ViewSet actions

f323989

rpkilby force-pushed theviewset-actions branch fromdeb0477 tof323989Compare

June 25, 2018 17:50

Document extra action method mapping

d1676f9

Copy link

ContributorAuthor

rpkilby commentedJun 25, 2018

Okay, added some documentation. This includes:

Updated theVIEW_NAME_FUNCTION/VIEW_DESCRIPTION_FUNCTION docs to the new signature, and documented the relevantViewSet optional arguments (name,suffix,detail,description).
Document the new method mapping enhancement for theaction decorator.

rpkilby mentioned this pull request

Jun 26, 2018

Feature/action docs sections#6060

Merged

carltongibson approved these changes

Jul 6, 2018

View reviewed changes

carltongibson merged commit0148a9f intoencode:master

Jul 6, 2018

rpkilby deleted the viewset-actions branch

July 6, 2018 14:26

rpkilby mentioned this pull request

Jul 10, 2018

Fix action support for ViewSet suffixes#6081

Merged

3 tasks

Copy link

noisy commentedJul 14, 2018

I just found this pull request, because I tried to make my actions visible in browsable api. Thank you for this work.

Right now I am developing my project installing DRF directly from git.@carltongibson - do you know when we can expect a new version of DRF with this feature included?

Copy link

ContributorAuthor

rpkilby commentedJul 14, 2018

Brief aside: I know there is a little more work that needs to be done before a 3.9 release can be shipped, but one minor blocker is#6081, which fixes a flaw in this pull request. Ishould have time to work on it this weekend.

Copy link

Collaborator

carltongibson commentedJul 15, 2018

@noisy we’re working on the 3.9 release now. I would think a few weeks. Pip’s VCS support is first class. There’s no reason why you can’t use the version from master.

axnsan12 mentioned this pull request

Aug 6, 2018

drf-yasg does not work with DRF 3.9 action mappingsaxnsan12/drf-yasg#177

Closed

OskarPersson mentioned this pull request

Oct 19, 2018

Add support for Django Rest Framework 3.9tuffnatty/drf-proxy-pagination#4

Merged

soerface mentioned this pull request

Jan 18, 2019

Improve documentation regarding serializer class on extra actions.#6410

Closed

shanemcd pushed a commit to shanemcd/awx that referenced this pull request

Jun 18, 2019

Update get_view_description to conform to changes in DRF's version

53d7ac9

relatedencode/django-rest-framework#5605

pchiquet pushed a commit to pchiquet/django-rest-framework that referenced this pull request

Nov 17, 2020

Improvements to ViewSet extra actions (encode#5605)

0bc451f

* View suffix already set by initializer* Add 'name' and 'description' attributes to ViewSetViewSets may now provide their `name` and `description` attributesdirectly, instead of relying on view introspection to derive them.These attributes may also be provided with the view's initkwargs.The ViewSet `name` and `suffix` initkwargs are mutually exclusive.The `action` decorator now provides the `name` and `description` tothe view's initkwargs. By default, these values are derived from themethod name and its docstring. The `name` may be overridden by providingit as an argument to the decorator.The `get_view_name` and `get_view_description` hooks now provide theview instance to the handler, instead of the view class. The defaultimplementations of these handlers now respect the `name`/`description`.* Add 'extra actions' to ViewSet & browsable APIs* Update simple router testsRemoved old test logic around link/action decorators from `v2.3`. Alsosimplified the test by making the results explicit instead of computed.* Add method mapping to ViewSet actions* Document extra action method mapping

Copy link

Contributor

gabn88 commentedMar 22, 2021•
edited
Loading

@carltongibson @rpkilby
Great work with this addition!
I was wondering for almost a year why I couldn't get the "extra actions" button on my production site. In tests it worked, but on my live site I just couldn't get it working.
Until I saw:#7500 which fixed it right away.
Would it be possible to incorporate this?