Latest docs build

This commit is contained in:
Tom Christie 2012-10-17 13:50:08 +01:00
parent 455a2ab325
commit f817d4335a
34 changed files with 236 additions and 92 deletions

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -115,11 +115,12 @@
<li class="main"><a href="#authentication">Authentication</a></li>
<li><a href="#how-authentication-is-determined">How authentication is determined</a></li>
<li><a href="#setting-the-authentication-policy">Setting the authentication policy</a></li>
<li class="main"><a href="#api-reference">API Reference</a></li>
<li><a href="#basicauthentication">BasicAuthentication</a></li>
<li><a href="#tokenauthentication">TokenAuthentication</a></li>
<li><a href="#oauthauthentication">OAuthAuthentication</a></li>
<li><a href="#sessionauthentication">SessionAuthentication</a></li>
<li><a href="#custom-authentication-policies">Custom authentication policies</a></li>
<li class="main"><a href="#custom-authentication">Custom authentication</a></li>
</ul>
</div>
@ -173,6 +174,7 @@ def example_view(request, format=None):
}
return Response(content)
</code></pre>
<h1 id="api-reference">API Reference</h1>
<h2 id="basicauthentication">BasicAuthentication</h2>
<p>This policy uses <a href="http://tools.ietf.org/html/rfc2617">HTTP Basic Authentication</a>, signed against a user's username and password. Basic authentication is generally only appropriate for testing.</p>
<p>If successfully authenticated, <code>BasicAuthentication</code> provides the following credentials.</p>
@ -213,7 +215,7 @@ print token.key
<li><code>request.user</code> will be a <code>django.contrib.auth.models.User</code> instance.</li>
<li><code>request.auth</code> will be <code>None</code>.</li>
</ul>
<h2 id="custom-authentication-policies">Custom authentication policies</h2>
<h1 id="custom-authentication">Custom authentication</h1>
<p>To implement a custom authentication policy, subclass <code>BaseAuthentication</code> and override the <code>.authenticate(self, request)</code> method. The method should return a two-tuple of <code>(user, auth)</code> if authentication succeeds, or <code>None</code> otherwise.</p>
</div><!--/span-->
</div><!--/row-->

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -155,7 +155,7 @@ Content-Length: 42
</code></pre>
<h2 id="apiexception">APIException</h2>
<p><strong>Signature:</strong> <code>APIException(detail=None)</code></p>
<p>The base class for all exceptions raised inside REST framework.</p>
<p>The <strong>base class</strong> for all exceptions raised inside REST framework.</p>
<p>To provide a custom exception, subclass <code>APIException</code> and set the <code>.status_code</code> and <code>.detail</code> properties on the class.</p>
<h2 id="parseerror">ParseError</h2>
<p><strong>Signature:</strong> <code>ParseError(detail=None)</code></p>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -190,12 +190,21 @@
<h1 id="typed-fields">Typed Fields</h1>
<p>These fields represent basic datatypes, and support both reading and writing values.</p>
<h2 id="booleanfield">BooleanField</h2>
<p>A Boolean representation, corresponds to <code>django.db.models.fields.BooleanField</code>.</p>
<h2 id="charfield">CharField</h2>
<p>A text representation, optionally validates the text to be shorter than <code>max_length</code> and longer than <code>min_length</code>, corresponds to <code>django.db.models.fields.CharField</code>
or <code>django.db.models.fields.TextField</code>.</p>
<p><strong>Signature:</strong> <code>CharField([max_length=&lt;Integer&gt;[, min_length=&lt;Integer&gt;]])</code></p>
<h2 id="emailfield">EmailField</h2>
<p>A text representation, validates the text to be a valid e-mail adress. Corresponds to <code>django.db.models.fields.EmailField</code></p>
<h2 id="datefield">DateField</h2>
<p>A date representation. Corresponds to <code>django.db.models.fields.DateField</code></p>
<h2 id="datetimefield">DateTimeField</h2>
<p>A date and time representation. Corresponds to <code>django.db.models.fields.DateTimeField</code></p>
<h2 id="integerfield">IntegerField</h2>
<p>An integer representation. Corresponds to <code>django.db.models.fields.IntegerField</code>, <code>django.db.models.fields.SmallIntegerField</code>, <code>django.db.models.fields.PositiveIntegerField</code> and <code>django.db.models.fields.PositiveSmallIntegerField</code></p>
<h2 id="floatfield">FloatField</h2>
<p>A floating point representation. Corresponds to <code>django.db.models.fields.FloatField</code>.</p>
<hr />
<h1 id="relational-fields">Relational Fields</h1>
<p>Relational fields are used to represent model relationships. They can be applied to <code>ForeignKey</code>, <code>ManyToManyField</code> and <code>OneToOneField</code> relationships, as well as to reverse relationships, and custom relationships such as <code>GenericForeignKey</code>.</p>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -116,7 +116,7 @@
<li><a href="#paginating-basic-data">Paginating basic data</a></li>
<li><a href="#paginating-querysets">Paginating QuerySets</a></li>
<li><a href="#pagination-in-the-generic-views">Pagination in the generic views</a></li>
<li><a href="#creating-custom-pagination-serializers">Creating custom pagination serializers</a></li>
<li><a href="#custom-pagination-serializers">Custom pagination serializers</a></li>
</ul>
</div>
@ -208,7 +208,7 @@ def user_list(request):
paginate_by = 10
</code></pre>
<p>For more complex requirements such as serialization that differs depending on the requested media type you can override the <code>.get_paginate_by()</code> and <code>.get_pagination_serializer_class()</code> methods.</p>
<h2 id="creating-custom-pagination-serializers">Creating custom pagination serializers</h2>
<h2 id="custom-pagination-serializers">Custom pagination serializers</h2>
<p>To create a custom pagination serializer class you should override <code>pagination.BasePaginationSerializer</code> and set the fields that you want the serializer to return.</p>
<p>You can also override the name used for the object list field, by setting the <code>results_field</code> attribute, which defaults to <code>'results'</code>.</p>
<p>For example, to nest a pair of links labelled 'prev' and 'next', and set the name for the results field to 'objects', you might use something like this.</p>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -113,12 +113,17 @@
<div id="table-of-contents">
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
<li class="main"><a href="#parsers">Parsers</a></li>
<li><a href="#how-the-parser-is-determined">How the parser is determined</a></li>
<li><a href="#setting-the-parsers">Setting the parsers</a></li>
<li class="main"><a href="#api-reference">API Reference</a></li>
<li><a href="#jsonparser">JSONParser</a></li>
<li><a href="#yamlparser">YAMLParser</a></li>
<li><a href="#xmlparser">XMLParser</a></li>
<li><a href="#formparser">FormParser</a></li>
<li><a href="#multipartparser">MultiPartParser</a></li>
<li><a href="#custom-parsers">Custom parsers</a></li>
<li class="main"><a href="#custom-parsers">Custom parsers</a></li>
<li><a href="#example">Example</a></li>
<li><a href="#uploading-file-content">Uploading file content</a></li>
</ul>
</div>
@ -133,12 +138,106 @@ structured formats for sending data than form-encoded, since they're
sending more complex data than simple forms</p>
<p>&mdash; Malcom Tredinnick, <a href="https://groups.google.com/d/topic/django-developers/dxI4qVzrBY4/discussion">Django developers group</a></p>
</blockquote>
<p>REST framework includes a number of built in Parser classes, that allow you to accept requests with various media types. There is also support for defining your own custom parsers, which gives you the flexiblity to design the media types that your API accepts.</p>
<h2 id="how-the-parser-is-determined">How the parser is determined</h2>
<p>The set of valid parsers for a view is always defined as a list of classes. When either <code>request.DATA</code> or <code>request.FILES</code> is accessed, REST framework will examine the <code>Content-Type</code> header on the incoming request, and determine which parser to use to parse the request content.</p>
<h2 id="setting-the-parsers">Setting the parsers</h2>
<p>The default set of parsers may be set globally, using the <code>DEFAULT_PARSERS</code> setting. For example, the following settings would allow requests with <code>YAML</code> content.</p>
<pre class="prettyprint lang-py"><code>REST_FRAMEWORK = {
'DEFAULT_PARSERS': (
'rest_framework.parsers.YAMLParser',
)
}
</code></pre>
<p>You can also set the renderers used for an individual view, using the <code>APIView</code> class based views.</p>
<pre class="prettyprint lang-py"><code>class ExampleView(APIView):
"""
A view that can accept POST requests with YAML content.
"""
parser_classes = (YAMLParser,)
def post(self, request, format=None):
return Response({'received data': request.DATA})
</code></pre>
<p>Or, if you're using the <code>@api_view</code> decorator with function based views.</p>
<pre class="prettyprint lang-py"><code>@api_view(('POST',)),
@parser_classes((YAMLParser,))
def example_view(request, format=None):
"""
A view that can accept POST requests with YAML content.
"""
return Response({'received data': request.DATA})
</code></pre>
<hr />
<h1 id="api-reference">API Reference</h1>
<h2 id="jsonparser">JSONParser</h2>
<p>Parses <code>JSON</code> request content.</p>
<p><strong>.media_type</strong>: <code>application/json</code></p>
<h2 id="yamlparser">YAMLParser</h2>
<p>Parses <code>YAML</code> request content.</p>
<p><strong>.media_type</strong>: <code>application/yaml</code></p>
<h2 id="xmlparser">XMLParser</h2>
<p>Parses REST framework's default style of <code>XML</code> request content.</p>
<p>Note that the <code>XML</code> markup language is used typically used as the base language for more strictly defined domain-specific languages, such as <code>RSS</code>, <code>Atom</code>, and <code>XHTML</code>.</p>
<p>If you are considering using <code>XML</code> for your API, you may want to consider implementing a custom renderer and parser for your specific requirements, and using an existing domain-specific media-type, or creating your own custom XML-based media-type.</p>
<p><strong>.media_type</strong>: <code>application/xml</code></p>
<h2 id="formparser">FormParser</h2>
<p>Parses HTML form content. <code>request.DATA</code> will be populated with a <code>QueryDict</code> of data, <code>request.FILES</code> will be populated with an empty <code>QueryDict</code> of data.</p>
<p>You will typically want to use both <code>FormParser</code> and <code>MultiPartParser</code> together in order to fully support HTML form data.</p>
<p><strong>.media_type</strong>: <code>application/x-www-form-urlencoded</code></p>
<h2 id="multipartparser">MultiPartParser</h2>
<h2 id="custom-parsers">Custom parsers</h2>
<p>Parses multipart HTML form content, which supports file uploads. Both <code>request.DATA</code> and <code>request.FILES</code> will be populated with a <code>QueryDict</code>.</p>
<p>You will typically want to use both <code>FormParser</code> and <code>MultiPartParser</code> together in order to fully support HTML form data.</p>
<p><strong>.media_type</strong>: <code>multipart/form-data</code></p>
<hr />
<h1 id="custom-parsers">Custom parsers</h1>
<p>To implement a custom parser, you should override <code>BaseParser</code>, set the <code>.media_type</code> property, and implement the <code>.parse_stream(self, stream, parser_context)</code> method.</p>
<p>The method should return the data that will be used to populate the <code>request.DATA</code> property.</p>
<p>The arguments passed to <code>.parse_stream()</code> are:</p>
<h3 id="stream">stream</h3>
<p>A stream-like object representing the body of the request.</p>
<h3 id="parser_context">parser_context</h3>
<p>If supplied, this argument will be a dictionary containing any additional context that may be required to parse the request content. By default it includes the keys <code>'upload_handlers'</code> and <code>'meta'</code>, which contain the values of the <code>request.upload_handlers</code> and <code>request.meta</code> properties.</p>
<h2 id="example">Example</h2>
<p>The following is an example plaintext parser that will populate the <code>request.DATA</code> property with a string representing the body of the request. </p>
<pre class="prettyprint lang-py"><code>class PlainTextParser(BaseParser):
"""
Plain text parser.
"""
media_type = 'text/plain'
def parse_stream(self, stream, parser_context=None):
"""
Simply return a string representing the body of the request.
"""
return stream.read()
</code></pre>
<h2 id="uploading-file-content">Uploading file content</h2>
<p>If your custom parser needs to support file uploads, you may return a <code>DataAndFiles</code> object from the <code>.parse_stream()</code> method. <code>DataAndFiles</code> should be instantiated with two arguments. The first argument will be used to populate the <code>request.DATA</code> property, and the second argument will be used to populate the <code>request.FILES</code> property.</p>
<p>For example:</p>
<pre class="prettyprint lang-py"><code>class SimpleFileUploadParser(BaseParser):
"""
A naive raw file upload parser.
"""
def parse_stream(self, stream, parser_context):
content = stream.read()
name = 'example.dat'
content_type = 'application/octet-stream'
size = len(content)
charset = 'utf-8'
# Write a temporary file based on the request content
temp = tempfile.NamedTemporaryFile(delete=False)
temp.write(content)
uploaded = UploadedFile(temp, name, content_type, size, charset)
# Return the uploaded file
data = {}
files = {name: uploaded}
return DataAndFiles(data, files)
</code></pre>
</div><!--/span-->
</div><!--/row-->
</div><!--/.fluid-container-->

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -116,11 +116,12 @@
<li><a href="#how-permissions-are-determined">How permissions are determined</a></li>
<li><a href="#object-level-permissions">Object level permissions</a></li>
<li><a href="#setting-the-permission-policy">Setting the permission policy</a></li>
<li class="main"><a href="#api-reference">API Reference</a></li>
<li><a href="#isauthenticated">IsAuthenticated</a></li>
<li><a href="#isadminuser">IsAdminUser</a></li>
<li><a href="#isauthenticatedorreadonly">IsAuthenticatedOrReadOnly</a></li>
<li><a href="#djangomodelpermissions">DjangoModelPermissions</a></li>
<li><a href="#custom-permissions">Custom permissions</a></li>
<li class="main"><a href="#custom-permissions">Custom permissions</a></li>
</ul>
</div>
@ -170,6 +171,7 @@ def example_view(request, format=None):
}
return Response(content)
</code></pre>
<h1 id="api-reference">API Reference</h1>
<h2 id="isauthenticated">IsAuthenticated</h2>
<p>The <code>IsAuthenticated</code> permission class will deny permission to any unauthenticated user, and allow permission otherwise.</p>
<p>This permission is suitable if you want your API to only be accessible to registered users.</p>
@ -189,7 +191,7 @@ def example_view(request, format=None):
<p>The default behaviour can also be overridden to support custom model permissions. For example, you might want to include a <code>view</code> model permission for <code>GET</code> requests.</p>
<p>To use custom model permissions, override <code>DjangoModelPermissions</code> and set the <code>.perms_map</code> property. Refer to the source code for details.</p>
<p>The <code>DjangoModelPermissions</code> class also supports object-level permissions. Third-party authorization backends such as <a href="https://github.com/lukaszb/django-guardian">django-guardian</a> that provide object-level permissions should work just fine with <code>DjangoModelPermissions</code> without any custom configuration required.</p>
<h2 id="custom-permissions">Custom permissions</h2>
<h1 id="custom-permissions">Custom permissions</h1>
<p>To implement a custom permission, override <code>BasePermission</code> and implement the <code>.has_permission(self, request, view, obj=None)</code> method.</p>
<p>The method should return <code>True</code> if the request should be granted access, and <code>False</code> otherwise.</p>
</div><!--/span-->

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -123,7 +123,8 @@
<li><a href="#xmlrenderer">XMLRenderer</a></li>
<li><a href="#htmlrenderer">HTMLRenderer</a></li>
<li><a href="#browsableapirenderer">BrowsableAPIRenderer</a></li>
<li><a href="#custom-renderers">Custom renderers</a></li>
<li class="main"><a href="#custom-renderers">Custom renderers</a></li>
<li><a href="#example">Example</a></li>
<li class="main"><a href="#advanced-renderer-usage">Advanced renderer usage</a></li>
<li><a href="#varying-behaviour-by-media-type">Varying behaviour by media type</a></li>
<li><a href="#designing-your-media-types">Designing your media types</a></li>
@ -166,8 +167,8 @@
return Response(content)
</code></pre>
<p>Or, if you're using the <code>@api_view</code> decorator with function based views.</p>
<pre class="prettyprint lang-py"><code>@api_view('GET'),
@renderer_classes(JSONRenderer, JSONPRenderer)
<pre class="prettyprint lang-py"><code>@api_view(('GET',)),
@renderer_classes((JSONRenderer, JSONPRenderer))
def user_count_view(request, format=None):
"""
A view that returns the count of active users, in JSON or JSONp.
@ -183,17 +184,26 @@ def user_count_view(request, format=None):
<hr />
<h1 id="api-reference">API Reference</h1>
<h2 id="jsonrenderer">JSONRenderer</h2>
<p><strong>.media_type:</strong> <code>application/json</code></p>
<p><strong>.format:</strong> <code>'.json'</code></p>
<p>Renders the request data into <code>JSON</code>.</p>
<p>The client may additionally include an <code>'indent'</code> media type parameter, in which case the returned <code>JSON</code> will be indented. For example <code>Accept: application/json; indent=4</code>.</p>
<p><strong>.media_type</strong>: <code>application/json</code></p>
<p><strong>.format</strong>: <code>'.json'</code></p>
<h2 id="jsonprenderer">JSONPRenderer</h2>
<p><strong>.media_type:</strong> <code>application/javascript</code></p>
<p><strong>.format:</strong> <code>'.jsonp'</code></p>
<p>Renders the request data into <code>JSONP</code>. The <code>JSONP</code> media type provides a mechanism of allowing cross-domain AJAX requests, by wrapping a <code>JSON</code> response in a javascript callback.</p>
<p>The javascript callback function must be set by the client including a <code>callback</code> URL query parameter. For example <code>http://example.com/api/users?callback=jsonpCallback</code>. If the callback function is not explicitly set by the client it will default to <code>'callback'</code>.</p>
<p><strong>Note</strong>: If you require cross-domain AJAX requests, you may also want to consider using <a href="http://en.wikipedia.org/wiki/Cross-origin_resource_sharing">CORS</a> as an alternative to <code>JSONP</code>.</p>
<p><strong>.media_type</strong>: <code>application/javascript</code></p>
<p><strong>.format</strong>: <code>'.jsonp'</code></p>
<h2 id="yamlrenderer">YAMLRenderer</h2>
<p><strong>.media_type:</strong> <code>application/yaml</code></p>
<p><strong>.format:</strong> <code>'.yaml'</code></p>
<p>Renders the request data into <code>YAML</code>. </p>
<p><strong>.media_type</strong>: <code>application/yaml</code></p>
<p><strong>.format</strong>: <code>'.yaml'</code></p>
<h2 id="xmlrenderer">XMLRenderer</h2>
<p><strong>.media_type:</strong> <code>application/xml</code></p>
<p><strong>.format:</strong> <code>'.xml'</code></p>
<p>Renders REST framework's default style of <code>XML</code> response content.</p>
<p>Note that the <code>XML</code> markup language is used typically used as the base language for more strictly defined domain-specific languages, such as <code>RSS</code>, <code>Atom</code>, and <code>XHTML</code>.</p>
<p>If you are considering using <code>XML</code> for your API, you may want to consider implementing a custom renderer and parser for your specific requirements, and using an existing domain-specific media-type, or creating your own custom XML-based media-type.</p>
<p><strong>.media_type</strong>: <code>application/xml</code></p>
<p><strong>.format</strong>: <code>'.xml'</code></p>
<h2 id="htmlrenderer">HTMLRenderer</h2>
<p>Renders data to HTML, using Django's standard template rendering.
Unlike other renderers, the data passed to the <code>Response</code> does not need to be serialized. Also, unlike other renderers, you may want to include a <code>template_name</code> argument when creating the <code>Response</code>.</p>
@ -218,15 +228,25 @@ Unlike other renderers, the data passed to the <code>Response</code> does not ne
</code></pre>
<p>You can use <code>HTMLRenderer</code> either to return regular HTML pages using REST framework, or to return both HTML and API responses from a single endpoint.</p>
<p>If you're building websites that use <code>HTMLRenderer</code> along with other renderer classes, you should consider listing <code>HTMLRenderer</code> as the first class in the <code>renderer_classes</code> list, so that it will be prioritised first even for browsers that send poorly formed <code>ACCEPT:</code> headers.</p>
<p><strong>.media_type:</strong> <code>text/html</code></p>
<p><strong>.format:</strong> <code>'.html'</code></p>
<p><strong>.media_type</strong>: <code>text/html</code></p>
<p><strong>.format</strong>: <code>'.html'</code></p>
<h2 id="browsableapirenderer">BrowsableAPIRenderer</h2>
<p>Renders data into HTML for the Browseable API. This renderer will determine which other renderer would have been given highest priority, and use that to display an API style response within the HTML page.</p>
<p><strong>.media_type:</strong> <code>text/html</code></p>
<p><strong>.format:</strong> <code>'.api'</code></p>
<h2 id="custom-renderers">Custom renderers</h2>
<p><strong>.media_type</strong>: <code>text/html</code></p>
<p><strong>.format</strong>: <code>'.api'</code></p>
<hr />
<h1 id="custom-renderers">Custom renderers</h1>
<p>To implement a custom renderer, you should override <code>BaseRenderer</code>, set the <code>.media_type</code> and <code>.format</code> properties, and implement the <code>.render(self, data, media_type=None, renderer_context=None)</code> method.</p>
<p>For example:</p>
<p>The arguments passed to the <code>.render()</code> method are:</p>
<h3 id="data"><code>data</code></h3>
<p>The request data, as set by the <code>Response()</code> instantiation.</p>
<h3 id="media_typenone"><code>media_type=None</code></h3>
<p>Optional. If provided, this is the accepted media type, as determined by the content negotiation stage. Depending on the client's <code>Accept:</code> header, this may be more specific than the renderer's <code>media_type</code> attribute, and may include media type parameters. For example <code>"application/json; nested=true"</code>.</p>
<h3 id="renderer_contextnone"><code>renderer_context=None</code></h3>
<p>Optional. If provided, this is a dictionary of contextual information provided by the view.
By default this will include the following keys: <code>view</code>, <code>request</code>, <code>response</code>, <code>args</code>, <code>kwargs</code>.</p>
<h2 id="example">Example</h2>
<p>The following is an example plaintext renderer that will return a response with the <code>data</code> parameter as the content of the response.</p>
<pre class="prettyprint lang-py"><code>from django.utils.encoding import smart_unicode
from rest_framework import renderers
@ -239,14 +259,6 @@ class PlainText(renderers.BaseRenderer):
return data
return smart_unicode(data)
</code></pre>
<p>The arguments passed to the <code>.render()</code> method are:</p>
<h4 id="data"><code>data</code></h4>
<p>The request data, as set by the <code>Response()</code> instantiation.</p>
<h4 id="media_typenone"><code>media_type=None</code></h4>
<p>Optional. If provided, this is the accepted media type, as determined by the content negotiation stage. Depending on the client's <code>Accept:</code> header, this may be more specific than the renderer's <code>media_type</code> attribute, and may include media type parameters. For example <code>"application/json; nested=true"</code>.</p>
<h4 id="renderer_contextnone"><code>renderer_context=None</code></h4>
<p>Optional. If provided, this is a dictionary of contextual information provided by the view.
By default this will include the following keys: <code>view</code>, <code>request</code>, <code>response</code>, <code>args</code>, <code>kwargs</code>.</p>
<hr />
<h1 id="advanced-renderer-usage">Advanced renderer usage</h1>
<p>You can do some pretty flexible things using REST framework's renderers. Some examples...</p>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -126,6 +126,7 @@
<li><a href="#method">.method</a></li>
<li><a href="#content_type">.content_type</a></li>
<li><a href="#stream">.stream</a></li>
<li class="main"><a href="#standard-httprequest-attributes">Standard HttpRequest attributes</a></li>
</ul>
</div>
@ -160,6 +161,7 @@
<p>You won't typically need to access this property.</p>
<hr />
<p><strong>Note:</strong> If a client sends malformed content, then accessing <code>request.DATA</code> or <code>request.FILES</code> may raise a <code>ParseError</code>. By default REST framework's <code>APIView</code> class or <code>@api_view</code> decorator will catch the error and return a <code>400 Bad Request</code> response.</p>
<p>If a client sends a request with a content-type that cannot be parsed then a <code>UnsupportedMediaType</code> exception will be raised, which by default will be caught and return a <code>415 Unsupported Media Type</code> response.</p>
<hr />
<h1 id="authentication">Authentication</h1>
<p>REST framework provides flexbile, per-request authentication, that gives you the abilty to:</p>
@ -181,7 +183,7 @@
<p>You won't typically need to access this property.</p>
<hr />
<h1 id="browser-enhancements">Browser enhancements</h1>
<p>REST framework supports a few browser enhancments such as broser-based <code>PUT</code> and <code>DELETE</code> forms.</p>
<p>REST framework supports a few browser enhancments such as browser-based <code>PUT</code> and <code>DELETE</code> forms.</p>
<h2 id="method">.method</h2>
<p><code>request.method</code> returns the <strong>uppercased</strong> string representation of the request's HTTP method.</p>
<p>Browser-based <code>PUT</code> and <code>DELETE</code> forms are transparently supported.</p>
@ -199,6 +201,10 @@
<p>If you do need to access the raw content directly, you should use the <code>.stream</code> property in preference to using <code>request.content</code>, as it provides transparent support for browser-based non-form content.</p>
<p>For more information see the <a href="../topics/browser-enhancements">browser enhancements documentation</a>. <br />
</p>
<hr />
<h1 id="standard-httprequest-attributes">Standard HttpRequest attributes</h1>
<p>As REST framework's <code>Request</code> extends Django's <code>HttpRequest</code>, all the other standard attributes and methods are also available. For example the <code>request.META</code> dictionary is available as normal.</p>
<p>Note that due to implementation reasons the <code>Request</code> class does not inherit from <code>HttpRequest</code> class, but instead extends the class using composition.</p>
</div><!--/span-->
</div><!--/row-->
</div><!--/.fluid-container-->

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -113,10 +113,8 @@
<div id="table-of-contents">
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
<li class="main"><a href="#responses">Responses</a></li>
<li class="main"><a href="#methods">Methods</a></li>
<li class="main"><a href="#creating-responses">Creating responses</a></li>
<li><a href="#response()">Response()</a></li>
<li><a href="#render()">.render()</a></li>
<li><a href="#standard-response-methods">Standard response methods</a></li>
<li class="main"><a href="#attributes">Attributes</a></li>
<li><a href="#data">.data</a></li>
<li><a href="#status_code">.status_code</a></li>
@ -125,6 +123,8 @@
<li><a href="#accepted_renderer">.accepted_renderer</a></li>
<li><a href="#accepted_media_type">.accepted_media_type</a></li>
<li><a href="#renderer_context">.renderer_context</a></li>
<li class="main"><a href="#standard-httpresponse-attributes">Standard HttpResponse attributes</a></li>
<li><a href="#render()">.render()</a></li>
</ul>
</div>
@ -142,7 +142,7 @@
<p>There's no requirement for you to use the <code>Response</code> class, you can also return regular <code>HttpResponse</code> objects from your views if you want, but it provides a nicer interface for returning Web API responses.</p>
<p>Unless you want to heavily customize REST framework for some reason, you should always use an <code>APIView</code> class or <code>@api_view</code> function for views that return <code>Response</code> objects. Doing so ensures that the view can perform content negotiation and select the appropriate renderer for the response, before it is returned from the view.</p>
<hr />
<h1 id="methods">Methods</h1>
<h1 id="creating-responses">Creating responses</h1>
<h2 id="response">Response()</h2>
<p><strong>Signature:</strong> <code>Response(data, status=None, template_name=None, headers=None)</code></p>
<p>Unlike regular <code>HttpResponse</code> objects, you do not instantiate <code>Response</code> objects with rendered content. Instead you pass in unrendered data, which may consist of any python primatives.</p>
@ -155,15 +155,6 @@
<li><code>template_name</code>: A template name to use if <code>HTMLRenderer</code> is selected.</li>
<li><code>headers</code>: A dictionary of HTTP headers to use in the response.</li>
</ul>
<h2 id="render">.render()</h2>
<p><strong>Signature:</strong> <code>.render()</code></p>
<p>This methd is called to render the serialized data of the response into the final response content. When <code>.render()</code> is called, the response content will be set to the result of calling the <code>.render(data, accepted_media_type)</code> method on the accepted renderer instance.</p>
<p>You won't typically need to call <code>.render()</code> yourself, as it's handled by Django's standard response cycle.</p>
<h2 id="standard-response-methods">Standard response methods</h2>
<p>The <code>Response</code> class extends <code>SimpleTemplateResponse</code>, and all the usual methods are also available on the response. For example you can set headers on the response in the standard way:</p>
<pre class="prettyprint lang-py"><code>response = Response()
response['Cache-Control'] = 'no-cache'
</code></pre>
<hr />
<h1 id="attributes">Attributes</h1>
<h2 id="data">.data</h2>
@ -183,6 +174,16 @@ response['Cache-Control'] = 'no-cache'
<h2 id="renderer_context">.renderer_context</h2>
<p>A dictionary of additional context information that will be passed to the renderer's <code>.render()</code> method.</p>
<p>Set automatically by the <code>APIView</code> or <code>@api_view</code> immediately before the response is returned from the view.</p>
<hr />
<h1 id="standard-httpresponse-attributes">Standard HttpResponse attributes</h1>
<p>The <code>Response</code> class extends <code>SimpleTemplateResponse</code>, and all the usual attributes and methods are also available on the response. For example you can set headers on the response in the standard way:</p>
<pre class="prettyprint lang-py"><code>response = Response()
response['Cache-Control'] = 'no-cache'
</code></pre>
<h2 id="render">.render()</h2>
<p><strong>Signature:</strong> <code>.render()</code></p>
<p>As with any other <code>TemplateResponse</code>, this methd is called to render the serialized data of the response into the final response content. When <code>.render()</code> is called, the response content will be set to the result of calling the <code>.render(data, accepted_media_type, renderer_context)</code> method on the <code>accepted_renderer</code> instance.</p>
<p>You won't typically need to call <code>.render()</code> yourself, as it's handled by Django's standard response cycle.</p>
</div><!--/span-->
</div><!--/row-->
</div><!--/.fluid-container-->

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -115,10 +115,11 @@
<li class="main"><a href="#throttling">Throttling</a></li>
<li><a href="#how-throttling-is-determined">How throttling is determined</a></li>
<li><a href="#setting-the-throttling-policy">Setting the throttling policy</a></li>
<li class="main"><a href="#api-reference">API Reference</a></li>
<li><a href="#anonratethrottle">AnonRateThrottle</a></li>
<li><a href="#userratethrottle">UserRateThrottle</a></li>
<li><a href="#scopedratethrottle">ScopedRateThrottle</a></li>
<li><a href="#custom-throttles">Custom throttles</a></li>
<li class="main"><a href="#custom-throttles">Custom throttles</a></li>
</ul>
</div>
@ -173,6 +174,7 @@ def example_view(request, format=None):
}
return Response(content)
</code></pre>
<h1 id="api-reference">API Reference</h1>
<h2 id="anonratethrottle">AnonRateThrottle</h2>
<p>The <code>AnonThrottle</code> will only ever throttle unauthenticated users. The IP address of the incoming request is used to generate a unique key to throttle against.</p>
<p>The allowed request rate is determined from one of the following (in order of preference).</p>
@ -237,7 +239,7 @@ class UploadView(APIView):
}
</code></pre>
<p>User requests to either <code>ContactListView</code> or <code>ContactDetailView</code> would be restricted to a total of 1000 requests per-day. User requests to <code>UploadView</code> would be restricted to 20 requests per day.</p>
<h2 id="custom-throttles">Custom throttles</h2>
<h1 id="custom-throttles">Custom throttles</h1>
<p>To create a custom throttle, override <code>BaseThrottle</code> and implement <code>.allow_request(request, view)</code>. The method should return <code>True</code> if the request should be allowed, and <code>False</code> otherwise.</p>
<p>Optionally you may also override the <code>.wait()</code> method. If implemented, <code>.wait()</code> should return a recomended number of seconds to wait before attempting the next request, or <code>None</code>. The <code>.wait()</code> method will only be called if <code>.allow_request()</code> has previously returned <code>False</code>.</p>
</div><!--/span-->

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -216,7 +216,7 @@ pip install -r optionals.txt
<li><a href="topics/rest-hypermedia-hateoas">REST, Hypermedia &amp; HATEOAS</a></li>
<li><a href="topics/contributing">Contributing to REST framework</a></li>
<li><a href="topics/migration">2.0 Migration Guide</a></li>
<li><a href="topics/changelog">Change Log</a></li>
<li><a href="topics/release-notes">Release Notes</a></li>
<li><a href="topics/credits">Credits</a></li>
</ul>
<h2 id="development">Development</h2>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -123,6 +123,10 @@
<div id="main-content" class="span9">
<h1 id="the-browsable-api">The Browsable API</h1>
<blockquote>
<p>It is a profoundly erroneous truism... that we should cultivate the habit of thinking of what we are doing. The precise opposite is the case. Civilization advances by extending the number of important operations which we can perform without thinking about them.</p>
<p>&mdash; <a href="http://en.wikiquote.org/wiki/Alfred_North_Whitehead">Alfred North Whitehead</a>, An Introduction to Mathematics (1911)</p>
</blockquote>
<p>API may stand for Application <em>Programming</em> Interface, but humans have to be able to read the APIs, too; someone has to do the programming. Django REST Framework supports generating human-friendly HTML output for each resource when the <code>HTML</code> format is requested. These pages allow for easy browsing of resources, as well as forms for submitting data to the resources using <code>POST</code>, <code>PUT</code>, and <code>DELETE</code>.</p>
<h2 id="urls">URLs</h2>
<p>If you include fully-qualified URLs in your resource output, they will be 'urlized' and made clickable for easy browsing by humans. The <code>rest_framework</code> package includes a <a href="../api-guide/reverse"><code>reverse</code></a> helper for this purpose.</p>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -168,6 +168,7 @@
<li>Jamie Matthews - <a href="https://github.com/j4mie">j4mie</a></li>
<li>Mattbo - <a href="https://github.com/mattbo">mattbo</a></li>
<li>Max Hurl - <a href="https://github.com/maximilianhurl">maximilianhurl</a></li>
<li>Tomi Pajunen - <a href="https://github.com/eofs">eofs</a></li>
</ul>
<p>Many thanks to everyone who's contributed to the project.</p>
<h2 id="additional-thanks">Additional thanks</h2>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -17,7 +17,7 @@
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<body onload="prettyPrint()" class="changelog-page">
<body onload="prettyPrint()" class="release-notes-page">
<div class="wrapper">
@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -112,7 +112,7 @@
-->
<div id="table-of-contents">
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
<li class="main"><a href="#change-log">Change Log</a></li>
<li class="main"><a href="#release-notes">Release Notes</a></li>
<li><a href="#200">2.0.0</a></li>
<li><a href="#040">0.4.0</a></li>
<li><a href="#033">0.3.3</a></li>
@ -132,10 +132,14 @@
</div>
<div id="main-content" class="span9">
<h1 id="change-log">Change Log</h1>
<h1 id="release-notes">Release Notes</h1>
<blockquote>
<p>Release Early, Release Often</p>
<p>&mdash; Eric S. Raymond, <a href="http://www.catb.org/~esr/writings/cathedral-bazaar/cathedral-bazaar/ar01s04.html">The Cathedral and the Bazaar</a>.</p>
</blockquote>
<h2 id="200">2.0.0</h2>
<ul>
<li><strong>Fix all of the things.</strong></li>
<li><strong>Fix all of the things.</strong> (Well, almost.)</li>
<li>For more information please see the <a href="migration">2.0 migration guide</a>.</li>
</ul>
<hr />

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>
@ -114,6 +114,8 @@
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
<li class="main"><a href="#rest,-hypermedia-&-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="#building-hypermedia-apis-with-rest-framework">Building Hypermedia APIs with REST framework</a></li>
<li><a href="#what-rest-framework-provides">What REST framework provides.</a></li>
<li><a href="#what-rest-framework-doesnt-provide">What REST framework doesn't provide.</a></li>
</ul>
</div>
@ -140,11 +142,11 @@ the Design of Network-based Software Architectures</a>.</li>
<p>For a more thorough background, check out Klabnik's <a href="http://blog.steveklabnik.com/posts/2012-02-27-hypermedia-api-reading-list">Hypermedia API reading list</a>.</p>
<h2 id="building-hypermedia-apis-with-rest-framework">Building Hypermedia APIs with REST framework</h2>
<p>REST framework is an agnositic Web API toolkit. It does help guide you towards building well-connected APIs, and makes it easy to design appropriate media types, but it does not strictly enforce any particular design style.</p>
<h3 id="what-rest-framework-does-provide">What REST framework <em>does</em> provide.</h3>
<h2 id="what-rest-framework-provides">What REST framework provides.</h2>
<p>It is self evident that REST framework makes it possible to build Hypermedia APIs. The browseable API that it offers is built on HTML - the hypermedia language of the web.</p>
<p>REST framework also includes <a href="../api-guide/serializers">serialization</a> and <a href="../api-guide/parsers">parser</a>/<a href="../api-guide/renderers">renderer</a> components that make it easy to build appropriate media types, <a href="../api-guide/fields">hyperlinked relations</a> for building well-connected systems, and great support for <a href="../api-guide/content-negotiation">content negotiation</a>.</p>
<h3 id="what-rest-framework-doesnt-provide">What REST framework <em>doesn't</em> provide.</h3>
<p>What REST framework doesn't do is give you is machine readable hypermedia formats such as <a href="http://www.amundsen.com/media-types/collection/">Collection+JSON</a> or HTML <a href="http://microformats.org/wiki/Main_Page">microformats</a> by default, or the ability to auto-magically create fully HATEOAS style APIs that include form descriptions, and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope.</p>
<h2 id="what-rest-framework-doesnt-provide">What REST framework doesn't provide.</h2>
<p>What REST framework doesn't do is give you is machine readable hypermedia formats such as <a href="http://www.amundsen.com/media-types/collection/">Collection+JSON</a> or HTML <a href="http://microformats.org/wiki/Main_Page">microformats</a> by default, or the ability to auto-magically create fully HATEOAS style APIs that include hypermedia-based form descriptions and semantically labelled hyperlinks. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope.</p>
</div><!--/span-->
</div><!--/row-->
</div><!--/.fluid-container-->

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>

View File

@ -78,7 +78,7 @@
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/changelog">Change Log</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
</ul>
</li>