You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Docs: move path converter into a separate section (#9524)
And remove note regarding only working with Django 2.x or above, as it's been a while the feature is present, and DRF only supports Django 4.2+.
I was looking for this but couldn't see it in the docs, having it in a separate section would make it easier to find and link to.
Moreover, as it stands, one might think that the feature is limited to SimpleRouter, while it's also available for DefaultRouter.
Copy file name to clipboardExpand all lines: docs/api-guide/routers.md
+19-19Lines changed: 19 additions & 19 deletions
Original file line number
Diff line number
Diff line change
@@ -142,6 +142,24 @@ The above example would now generate the following URL pattern:
142
142
* URL path: `^users/{pk}/change-password/$`
143
143
* URL name: `'user-change_password'`
144
144
145
+
### Using Django `path()` with routers
146
+
147
+
By default, the URLs created by routers use regular expressions. This behavior can be modified by setting the `use_regex_path` argument to `False` when instantiating the router, in this case [path converters][path-converters-topic-reference] are used. For example:
148
+
149
+
router = SimpleRouter(use_regex_path=False)
150
+
151
+
The router will match lookup values containing any characters except slashes and period characters. For a more restrictive (or lenient) lookup pattern, set the `lookup_value_regex` attribute on the viewset or `lookup_value_converter` if using path converters. For example, you can limit the lookup to valid UUIDs:
152
+
153
+
class MyModelViewSet(mixins.RetrieveModelMixin, viewsets.GenericViewSet):
154
+
lookup_field = 'my_model_id'
155
+
lookup_value_regex = '[0-9a-f]{32}'
156
+
157
+
class MyPathModelViewSet(mixins.RetrieveModelMixin, viewsets.GenericViewSet):
158
+
lookup_field = 'my_model_uuid'
159
+
lookup_value_converter = 'uuid'
160
+
161
+
Note that path converters will be used on all URLs registered in the router, including viewset actions.
162
+
145
163
# API Guide
146
164
147
165
## SimpleRouter
@@ -160,30 +178,13 @@ This router includes routes for the standard set of `list`, `create`, `retrieve`
160
178
<tr><td>{prefix}/{lookup}/{url_path}/</td><td>GET, or as specified by `methods` argument</td><td>`@action(detail=True)` decorated method</td><td>{basename}-{url_name}</td></tr>
161
179
</table>
162
180
163
-
By default the URLs created by `SimpleRouter` are appended with a trailing slash.
181
+
By default, the URLs created by `SimpleRouter` are appended with a trailing slash.
164
182
This behavior can be modified by setting the `trailing_slash` argument to `False` when instantiating the router. For example:
165
183
166
184
router = SimpleRouter(trailing_slash=False)
167
185
168
186
Trailing slashes are conventional in Django, but are not used by default in some other frameworks such as Rails. Which style you choose to use is largely a matter of preference, although some javascript frameworks may expect a particular routing style.
169
187
170
-
By default the URLs created by `SimpleRouter` use regular expressions. This behavior can be modified by setting the `use_regex_path` argument to `False` when instantiating the router, in this case [path converters][path-converters-topic-reference] are used. For example:
171
-
172
-
router = SimpleRouter(use_regex_path=False)
173
-
174
-
**Note**: `use_regex_path=False` only works with Django 2.x or above, since this feature was introduced in 2.0.0. See [release note][simplified-routing-release-note]
175
-
176
-
177
-
The router will match lookup values containing any characters except slashes and period characters. For a more restrictive (or lenient) lookup pattern, set the `lookup_value_regex` attribute on the viewset or `lookup_value_converter` if using path converters. For example, you can limit the lookup to valid UUIDs:
178
-
179
-
class MyModelViewSet(mixins.RetrieveModelMixin, viewsets.GenericViewSet):
180
-
lookup_field = 'my_model_id'
181
-
lookup_value_regex = '[0-9a-f]{32}'
182
-
183
-
class MyPathModelViewSet(mixins.RetrieveModelMixin, viewsets.GenericViewSet):
184
-
lookup_field = 'my_model_uuid'
185
-
lookup_value_converter = 'uuid'
186
-
187
188
## DefaultRouter
188
189
189
190
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.
@@ -351,5 +352,4 @@ The [`DRF-extensions` package][drf-extensions] provides [routers][drf-extensions
0 commit comments