Skip to content

Commit 3ba3f45

Browse files
committed
Corrected docs on router include with namespaces.
For Django 2.0 you MUST provide `app_name` when using `namespace`. Closes #5659 Correct namespace reference Updated example without changing old text.
1 parent ea7d414 commit 3ba3f45

File tree

1 file changed

+13
-3
lines changed

1 file changed

+13
-3
lines changed

docs/api-guide/routers.md

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,14 +72,23 @@ Alternatively you can use Django's `include` function, like so…
7272
url(r'^', include(router.urls)),
7373
]
7474

75-
Router URL patterns can also be namespaces.
75+
Router URL patterns can also be included using _application_ and _instance_ namespaces.
76+
77+
To use an _application namespace_ pass a 2-tuple containing the `router.urls` and the app name.
78+
To use an _instance namespace_ pass the optional `namespace` parameter.
79+
80+
For example:
7681

7782
urlpatterns = [
7883
url(r'^forgot-password/$', ForgotPasswordFormView.as_view()),
79-
url(r'^api/', include(router.urls, namespace='api')),
84+
url(r'^api/', include((router.urls, 'app_name'), namespace='instance_name')),
8085
]
8186

82-
If using namespacing with hyperlinked serializers you'll also need to ensure that any `view_name` parameters on the serializers correctly reflect the namespace. In the example above you'd need to include a parameter such as `view_name='api:user-detail'` for serializer fields hyperlinked to the user detail view.
87+
If you pass the optional `namespace` parameter to create an _instance namespace_ then you **must** provide the _application namespace_ as well.
88+
See Django's [URL namespaces docs][url-namespace-docs] for more.
89+
90+
If using namespacing with hyperlinked serializers you'll also need to ensure that any `view_name` parameters on the serializers correctly reflect the namespace.
91+
In the example above you'd need to include a parameter such as `view_name='app_name:user-detail'` for serializer fields hyperlinked to the user detail view.
8392

8493
### Routing for extra actions
8594

@@ -315,3 +324,4 @@ The [`DRF-extensions` package][drf-extensions] provides [routers][drf-extensions
315324
[drf-extensions-nested-viewsets]: https://chibisov.github.io/drf-extensions/docs/#nested-routes
316325
[drf-extensions-collection-level-controllers]: https://chibisov.github.io/drf-extensions/docs/#collection-level-controllers
317326
[drf-extensions-customizable-endpoint-names]: https://chibisov.github.io/drf-extensions/docs/#controller-endpoint-name
327+
[url-namespace-docs]: https://docs.djangoproject.com/en/1.11/topics/http/urls/#url-namespaces

0 commit comments

Comments
 (0)