diff options
| author | Carlton Gibson | 2014-12-01 11:22:39 +0100 |
|---|---|---|
| committer | Carlton Gibson | 2014-12-01 11:22:39 +0100 |
| commit | ef26f43de4a0c9ac3081c06a383b5d3d4d007797 (patch) | |
| tree | bf6abcd15f0e58f4fa79a83cd4e051b8987dd311 /docs/api-guide/format-suffixes.md | |
| parent | c50a42bddc66e28d624cd3caadd2d63502ac2e6e (diff) | |
| parent | 72c4ec4e189796e506655e275cd9c77abe98e1b9 (diff) | |
| download | django-rest-framework-ef26f43de4a0c9ac3081c06a383b5d3d4d007797.tar.bz2 | |
Merge branch 'master' of github.com:tomchristie/django-rest-framework
Diffstat (limited to 'docs/api-guide/format-suffixes.md')
| -rw-r--r-- | docs/api-guide/format-suffixes.md | 12 |
1 files changed, 6 insertions, 6 deletions
diff --git a/docs/api-guide/format-suffixes.md b/docs/api-guide/format-suffixes.md index 76a3367b..20c1e995 100644 --- a/docs/api-guide/format-suffixes.md +++ b/docs/api-guide/format-suffixes.md @@ -1,4 +1,4 @@ -<a class="github" href="urlpatterns.py"></a> +source: urlpatterns.py # Format suffixes @@ -7,7 +7,7 @@ used all the time. > > — Roy Fielding, [REST discuss mailing list][cite] -A common pattern for Web APIs is to use filename extensions on URLs to provide an endpoint for a given media type. For example, 'http://example.com/api/users.json' to serve a JSON representation. +A common pattern for Web APIs is to use filename extensions on URLs to provide an endpoint for a given media type. For example, 'http://example.com/api/users.json' to serve a JSON representation. Adding format-suffix patterns to each individual entry in the URLconf for your API is error-prone and non-DRY, so REST framework provides a shortcut to adding these patterns to your URLConf. @@ -21,7 +21,7 @@ Arguments: * **urlpatterns**: Required. A URL pattern list. * **suffix_required**: Optional. A boolean indicating if suffixes in the URLs should be optional or mandatory. Defaults to `False`, meaning that suffixes are optional by default. -* **allowed**: Optional. A list or tuple of valid format suffixes. If not provided, a wildcard format suffix pattern will be used. +* **allowed**: Optional. A list or tuple of valid format suffixes. If not provided, a wildcard format suffix pattern will be used. Example: @@ -33,7 +33,7 @@ Example: url(r'^comments/$', views.comment_list), url(r'^comments/(?P<pk>[0-9]+)/$', views.comment_detail) ] - + urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'html']) When using `format_suffix_patterns`, you must make sure to add the `'format'` keyword argument to the corresponding views. For example: @@ -56,12 +56,12 @@ The name of the kwarg used may be modified by using the `FORMAT_SUFFIX_KWARG` se Also note that `format_suffix_patterns` does not support descending into `include` URL patterns. --- - + ## Accept headers vs. format suffixes There seems to be a view among some of the Web community that filename extensions are not a RESTful pattern, and that `HTTP Accept` headers should always be used instead. -It is actually a misconception. For example, take the following quote from Roy Fielding discussing the relative merits of query parameter media-type indicators vs. file extension media-type indicators: +It is actually a misconception. For example, take the following quote from Roy Fielding discussing the relative merits of query parameter media-type indicators vs. file extension media-type indicators: “That's why I always prefer extensions. Neither choice has anything to do with REST.” — Roy Fielding, [REST discuss mailing list][cite2] |
