<p>Section 6.2.1 does not say that content negotiation should be
used all the time.</p>
<p>— Roy Fielding, <ahref="http://tech.groups.yahoo.com/group/rest-discuss/message/5857">REST discuss mailing list</a></p>
</blockquote>
<p>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.</p>
<p>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.</p>
<p>Returns a URL pattern list which includes format suffix patterns appended to each of the URL patterns provided.</p>
<p>Arguments:</p>
<ul>
<li><strong>urlpatterns</strong>: Required. A URL pattern list.</li>
<li><strong>suffix_required</strong>: Optional. A boolean indicating if suffixes in the URLs should be optional or mandatory. Defaults to <code>False</code>, meaning that suffixes are optional by default.</li>
<li><strong>allowed</strong>: Optional. A list or tuple of valid format suffixes. If not provided, a wildcard format suffix pattern will be used.</li>
<p>When using <code>format_suffix_patterns</code>, you must make sure to add the <code>'format'</code> keyword argument to the corresponding views. For example:</p>
<pre><code>@api_view(['GET', 'POST'])
def comment_list(request, format=None):
# do stuff...
</code></pre>
<p>Or with class-based views:</p>
<pre><code>class CommentList(APIView):
def get(self, request, format=None):
# do stuff...
def post(self, request, format=None):
# do stuff...
</code></pre>
<p>The name of the kwarg used may be modified by using the <code>FORMAT_SUFFIX_KWARG</code> setting.</p>
<p>Also note that <code>format_suffix_patterns</code> does not support descending into <code>include</code> URL patterns.</p>
<h3id="using-with-i18n_patterns"><aclass="toclink"href="#using-with-i18n_patterns">Using with <code>i18n_patterns</code></a></h3>
<p>If using the <code>i18n_patterns</code> function provided by Django, as well as <code>format_suffix_patterns</code> you should make sure that the <code>i18n_patterns</code> function is applied as the final, or outermost function. For example:</p>
<p>An alternative to the format suffixes is to include the requested format in a query parameter. REST framework provides this option by default, and it is used in the browsable API to switch between differing available representations.</p>
<p>To select a representation using its short format, use the <code>format</code> query parameter. For example: <code>http://example.com/organizations/?format=csv</code>.</p>
<p>The name of this query parameter can be modified using the <code>URL_FORMAT_OVERRIDE</code> setting. Set the value to <code>None</code> to disable this behavior.</p>
<hr/>
<h2id="accept-headers-vs-format-suffixes"><aclass="toclink"href="#accept-headers-vs-format-suffixes">Accept headers vs. format suffixes</a></h2>
<p>There seems to be a view among some of the Web community that filename extensions are not a RESTful pattern, and that <code>HTTP Accept</code> headers should always be used instead.</p>
<p>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:</p>
<p>“That's why I always prefer extensions. Neither choice has anything to do with REST.”— Roy Fielding, <ahref="https://groups.yahoo.com/neo/groups/rest-discuss/conversations/topics/14844">REST discuss mailing list</a></p>
<p>The quote does not mention Accept headers, but it does make it clear that format suffixes should be considered an acceptable pattern.</p>
</div><!--/span-->
</div><!--/row-->
</div><!--/.fluid-container-->
</div><!--/.body content-->
<divid="push"></div>
</div><!--/.wrapper -->
<footerclass="span12">
<p>Documentation built with <ahref="http://www.mkdocs.org/">MkDocs</a>.
