<p><strong>Note</strong>: This is the documentation for the <strong>version 3.0</strong> of REST framework. Documentation for <ahref="http://tomchristie.github.io/rest-framework-2-docs/">version 2.4</a> is also available.</p>
<hr/>
<h1id="metadata">Metadata</h1>
<blockquote>
<p>[The <code>OPTIONS</code>] method allows a client to determine the options and/or requirements associated with a resource, or the capabilities of a server, without implying a resource action or initiating a resource retrieval.</p>
<p>REST framework includes a configurable mechanism for determining how your API should respond to <code>OPTIONS</code> requests. This allows you to return API schema or other resource information.</p>
<p>There are not currently any widely adopted conventions for exactly what style of response should be returned for HTTP <code>OPTIONS</code> requests, so we provide an ad-hoc style that returns some useful information.</p>
<p>Here's an example response that demonstrates the information that is returned by default.</p>
<pre><code>HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
{
"name": "To Do List",
"description": "List existing 'To Do' items, or create a new item.",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"POST": {
"note": {
"type": "string",
"required": false,
"read_only": false,
"label": "title",
"max_length": 100
}
}
}
}
</code></pre>
<h2id="setting-the-metadata-scheme">Setting the metadata scheme</h2>
<p>You can set the metadata class globally using the <code>'DEFAULT_METADATA_CLASS'</code> settings key:</p>
<p>Or you can set the metadata class individually for a view:</p>
<pre><code>class APIRoot(APIView):
metadata_class = APIRootMetadata
def get(self, request, format=None):
return Response({
...
})
</code></pre>
<p>The REST framework package only includes a single metadata class implementation, named <code>SimpleMetadata</code>. If you want to use an alternative style you'll need to implement a custom metadata class.</p>
<p>If you have specific requirements for creating schema endpoints that are accessed with regular <code>GET</code> requests, you might consider re-using the metadata API for doing so.</p>
<p>For example, the following additional route could be used on a viewset to provide a linkable schema endpoint.</p>
<pre><code>@list_route(methods=['GET'])
def schema(self, request):
meta = self.metadata_class()
data = meta.determine_metadata(request, self)
return Response(data)
</code></pre>
<p>There are a couple of reasons that you might choose to take this approach, including that <code>OPTIONS</code> responses <ahref="https://www.mnot.net/blog/2012/10/29/NO_OPTIONS">are not cacheable</a>.</p>
<p>If you want to provide a custom metadata class you should override <code>BaseMetadata</code> and implement the <code>determine_metadata(self, request, view)</code> method.</p>
<p>Useful things that you might want to do could include returning schema information, using a format such as <ahref="http://json-schema.org/">JSON schema</a>, or returning debug information to admin users.</p>
<h2id="example">Example</h2>
<p>The following class could be used to limit the information that is returned to <code>OPTIONS</code> requests.</p>
<pre><code>class MinimalMetadata(BaseMetadata):
"""
Don't include field and other information for `OPTIONS` requests.
Just return the name and description.
"""
def determine_metadata(self, request, view):
return {
'name': view.get_view_name(),
'description': view.get_view_description()
}
</code></pre>
</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>.</a>
