mirror of
https://github.com/encode/django-rest-framework.git
synced 2025-03-01 09:50:40 +03:00
88 lines
3.9 KiB
Markdown
88 lines
3.9 KiB
Markdown
<a class="github" href="routers.py"></a>
|
|
|
|
# Routers
|
|
|
|
> Resource routing allows you to quickly declare all of the common routes for a given resourceful controller. Instead of declaring separate routes for your index... a resourceful route declares them in a single line of code.
|
|
>
|
|
> — [Ruby on Rails Documentation][cite]
|
|
|
|
Some Web frameworks such as Rails provide functionality for automatically determining how the URLs for an application should be mapped to the logic that deals with handling incoming requests.
|
|
|
|
REST framework adds support for automatic URL routing to Django, and provides you with a simple, quick and consistent way of wiring your view logic to a set of URLs.
|
|
|
|
## Usage
|
|
|
|
Here's an example of a simple URL conf, that uses `DefaultRouter`.
|
|
|
|
router = routers.SimpleRouter()
|
|
router.register(r'users', UserViewSet, 'user')
|
|
router.register(r'accounts', AccountViewSet, 'account')
|
|
urlpatterns = router.urls
|
|
|
|
There are three arguments to the `register()` method:
|
|
|
|
* `prefix` - The URL prefix to use for this set of routes.
|
|
* `viewset` - The viewset class.
|
|
* `basename` - The base to use for the URL names that are created.
|
|
|
|
The example above would generate the following URL patterns:
|
|
|
|
* URL pattern: `^users/$` Name: `'user-list'`
|
|
* URL pattern: `^users/{pk}/$` Name: `'user-detail'`
|
|
* URL pattern: `^accounts/$` Name: `'account-list'`
|
|
* URL pattern: `^accounts/{pk}/$` Name: `'account-detail'`
|
|
|
|
### Extra link and actions
|
|
|
|
Any `@link` or `@action` methods on the viewsets will also be routed.
|
|
For example, a given method like this on the `UserViewSet` class:
|
|
|
|
@action(permission_classes=[IsAdminOrIsSelf])
|
|
def set_password(self, request, pk=None):
|
|
...
|
|
|
|
The following URL pattern would additionally be generated:
|
|
|
|
* URL pattern: `^users/{pk}/set_password/$` Name: `'user-set-password'`
|
|
|
|
|
|
|
|
# API Guide
|
|
|
|
## 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.
|
|
|
|
<table border=1>
|
|
<tr><th>URL Style</th><th>HTTP Method</th><th>Action</th><th>URL Name</th></tr>
|
|
<tr><td rowspan=2>{prefix}/</td><td>GET</td><td>list</td><td rowspan=2>{basename}-list</td></tr></tr>
|
|
<tr><td>POST</td><td>create</td></tr>
|
|
<tr><td rowspan=4>{prefix}/{lookup}/</td><td>GET</td><td>retrieve</td><td rowspan=4>{basename}-detail</td></tr></tr>
|
|
<tr><td>PUT</td><td>update</td></tr>
|
|
<tr><td>PATCH</td><td>partial_update</td></tr>
|
|
<tr><td>DELETE</td><td>destroy</td></tr>
|
|
<tr><td rowspan=2>{prefix}/{lookup}/{methodname}/</td><td>GET</td><td>@link decorated method</td><td rowspan=2>{basename}-{methodname}</td></tr>
|
|
<tr><td>POST</td><td>@action decorated method</td></tr>
|
|
</table>
|
|
|
|
## DefaultRouter
|
|
|
|
This router is similar to `SimpleRouter` as above, but additionally includes a default API root view, that returns a response containing hyperlinks to all the list views. It also generates routes for optional `.json` style format suffixes.
|
|
|
|
<table border=1>
|
|
<tr><th>URL Style</th><th>HTTP Method</th><th>Action</th><th>URL Name</th></tr>
|
|
<tr><td>[.format]</td><td>GET</td><td>automatically generated root view</td><td>api-root</td></tr></tr>
|
|
<tr><td rowspan=2>{prefix}/[.format]</td><td>GET</td><td>list</td><td rowspan=2>{basename}-list</td></tr></tr>
|
|
<tr><td>POST</td><td>create</td></tr>
|
|
<tr><td rowspan=4>{prefix}/{lookup}/[.format]</td><td>GET</td><td>retrieve</td><td rowspan=4>{basename}-detail</td></tr></tr>
|
|
<tr><td>PUT</td><td>update</td></tr>
|
|
<tr><td>PATCH</td><td>partial_update</td></tr>
|
|
<tr><td>DELETE</td><td>destroy</td></tr>
|
|
<tr><td rowspan=2>{prefix}/{lookup}/{methodname}/[.format]</td><td>GET</td><td>@link decorated method</td><td rowspan=2>{basename}-{methodname}</td></tr>
|
|
<tr><td>POST</td><td>@action decorated method</td></tr>
|
|
</table>
|
|
|
|
# Custom Routers
|
|
|
|
|
|
[cite]: http://guides.rubyonrails.org/routing.html |