mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-12-04 23:44:07 +03:00
Change package name: djangorestframework -> rest_framework
This commit is contained in:
Tom Christie
parent
8d14f74964
commit
e5c8c6ea50
|
|
@ -107,7 +107,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/authentication.py"><span class="label label-info">authentication.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/authentication.py"><span class="label label-info">authentication.py</span></a></p>
|
||||
<h1 id="authentication">Authentication</h1>
|
||||
<blockquote>
|
||||
<p>Auth needs to be pluggable.</p>
|
||||
|
|
@ -124,10 +124,10 @@
|
|||
<p>The value of <code>request.user</code> and <code>request.auth</code> for unauthenticated requests can be modified using the <code>UNAUTHENTICATED_USER</code> and <code>UNAUTHENTICATED_TOKEN</code> settings.</p>
|
||||
<h2 id="setting-the-authentication-policy">Setting the authentication policy</h2>
|
||||
<p>The default authentication policy may be set globally, using the <code>DEFAULT_AUTHENTICATION</code> setting. For example.</p>
|
||||
<pre class="prettyprint lang-py"><code>API_SETTINGS = {
|
||||
<pre class="prettyprint lang-py"><code>REST_FRAMEWORK = {
|
||||
'DEFAULT_AUTHENTICATION': (
|
||||
'djangorestframework.authentication.UserBasicAuthentication',
|
||||
'djangorestframework.authentication.SessionAuthentication',
|
||||
'rest_framework.authentication.UserBasicAuthentication',
|
||||
'rest_framework.authentication.SessionAuthentication',
|
||||
)
|
||||
}
|
||||
</code></pre>
|
||||
|
|
@ -164,9 +164,9 @@ def example_view(request, format=None):
|
|||
<p><strong>Note:</strong> If you use <code>BasicAuthentication</code> in production you must ensure that your API is only available over <code>https</code> only. You should also ensure that your API clients will always re-request the username and password at login, and will never store those details to persistent storage.</p>
|
||||
<h2 id="tokenauthentication">TokenAuthentication</h2>
|
||||
<p>This policy uses a simple token-based HTTP Authentication scheme. Token authentication is appropriate for client-server setups, such as native desktop and mobile clients.</p>
|
||||
<p>To use the <code>TokenAuthentication</code> policy, include <code>djangorestframework.authtoken</code> in your <code>INSTALLED_APPS</code> setting.</p>
|
||||
<p>To use the <code>TokenAuthentication</code> policy, include <code>rest_framework.authtoken</code> in your <code>INSTALLED_APPS</code> setting.</p>
|
||||
<p>You'll also need to create tokens for your users.</p>
|
||||
<pre class="prettyprint lang-py"><code>from djangorestframework.authtoken.models import Token
|
||||
<pre class="prettyprint lang-py"><code>from rest_framework.authtoken.models import Token
|
||||
|
||||
token = Token.objects.create(user=...)
|
||||
print token.key
|
||||
|
|
@ -177,7 +177,7 @@ print token.key
|
|||
<p>If successfully authenticated, <code>TokenAuthentication</code> provides the following credentials.</p>
|
||||
<ul>
|
||||
<li><code>request.user</code> will be a <code>django.contrib.auth.models.User</code> instance.</li>
|
||||
<li><code>request.auth</code> will be a <code>djangorestframework.tokenauth.models.BasicToken</code> instance.</li>
|
||||
<li><code>request.auth</code> will be a <code>rest_framework.tokenauth.models.BasicToken</code> instance.</li>
|
||||
</ul>
|
||||
<p><strong>Note:</strong> If you use <code>TokenAuthentication</code> in production you must ensure that your API is only available over <code>https</code> only.</p>
|
||||
<h2 id="oauthauthentication">OAuthAuthentication</h2>
|
||||
|
|
@ -185,7 +185,7 @@ print token.key
|
|||
<p>If successfully authenticated, <code>OAuthAuthentication</code> provides the following credentials.</p>
|
||||
<ul>
|
||||
<li><code>request.user</code> will be a <code>django.contrib.auth.models.User</code> instance.</li>
|
||||
<li><code>request.auth</code> will be a <code>djangorestframework.models.OAuthToken</code> instance.</li>
|
||||
<li><code>request.auth</code> will be a <code>rest_framework.models.OAuthToken</code> instance.</li>
|
||||
</ul>
|
||||
<h2 id="sessionauthentication">SessionAuthentication</h2>
|
||||
<p>This policy uses Django's default session backend for authentication. Session authentication is appropriate for AJAX clients that are running in the same session context as your website.</p>
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/negotiation.py"><span class="label label-info">negotiation.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/negotiation.py"><span class="label label-info">negotiation.py</span></a></p>
|
||||
<h1 id="content-negotiation">Content negotiation</h1>
|
||||
<blockquote>
|
||||
<p>HTTP has provisions for several mechanisms for "content negotiation" - the process of selecting the best representation for a given response when there are multiple representations available.</p>
|
||||
|
|
|
|||
|
|
@ -107,7 +107,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/exceptions.py"><span class="label label-info">exceptions.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/exceptions.py"><span class="label label-info">exceptions.py</span></a></p>
|
||||
<h1 id="exceptions">Exceptions</h1>
|
||||
<blockquote>
|
||||
<p>Exceptions… allow error handling to be organized cleanly in a central or high-level place within the program structure.</p>
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/urlpatterns.py"><span class="label label-info">urlpatterns.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/urlpatterns.py"><span class="label label-info">urlpatterns.py</span></a></p>
|
||||
<h1 id="format-suffixes">Format suffixes</h1>
|
||||
<blockquote>
|
||||
<p>Section 6.2.1 does not say that content negotiation should be
|
||||
|
|
|
|||
|
|
@ -100,8 +100,8 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/mixins.py"><span class="label label-info">mixins.py</span></a>
|
||||
<a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/generics.py"><span class="label label-info">generics.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/mixins.py"><span class="label label-info">mixins.py</span></a>
|
||||
<a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/generics.py"><span class="label label-info">generics.py</span></a></p>
|
||||
<h1 id="generic-views">Generic views</h1>
|
||||
<blockquote>
|
||||
<p>Django’s generic views... were developed as a shortcut for common usage patterns... They take certain common idioms and patterns found in view development and abstract them so that you can quickly write common views of data without having to repeat yourself.</p>
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/parsers.py"><span class="label label-info">parsers.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/parsers.py"><span class="label label-info">parsers.py</span></a></p>
|
||||
<h1 id="parsers">Parsers</h1>
|
||||
<h2 id="parserequest">.parse(request)</h2>
|
||||
</div><!--/span-->
|
||||
|
|
|
|||
|
|
@ -108,7 +108,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/permissions.py"><span class="label label-info">permissions.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/permissions.py"><span class="label label-info">permissions.py</span></a></p>
|
||||
<h1 id="permissions">Permissions</h1>
|
||||
<blockquote>
|
||||
<p>Authentication or identification by itself is not usually sufficient to gain access to information or code. For that, the entity requesting access must have authorization.</p>
|
||||
|
|
@ -126,9 +126,9 @@ If any permission check fails an <code>exceptions.PermissionDenied</code> except
|
|||
<p>Object level permissions are run by REST framework's generic views when <code>.get_object()</code> is called. As with view level permissions, an <code>exceptions.PermissionDenied</code> exception will be raised if the user is not allowed to act on the given object.</p>
|
||||
<h2 id="setting-the-permission-policy">Setting the permission policy</h2>
|
||||
<p>The default permission policy may be set globally, using the <code>DEFAULT_PERMISSIONS</code> setting. For example.</p>
|
||||
<pre class="prettyprint lang-py"><code>API_SETTINGS = {
|
||||
<pre class="prettyprint lang-py"><code>REST_FRAMEWORK = {
|
||||
'DEFAULT_PERMISSIONS': (
|
||||
'djangorestframework.permissions.IsAuthenticated',
|
||||
'rest_framework.permissions.IsAuthenticated',
|
||||
)
|
||||
}
|
||||
</code></pre>
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/renderers.py"><span class="label label-info">renderers.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/renderers.py"><span class="label label-info">renderers.py</span></a></p>
|
||||
<h1 id="renderers">Renderers</h1>
|
||||
<h2 id="renderresponse">.render(response)</h2>
|
||||
</div><!--/span-->
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/request.py"><span class="label label-info">request.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/request.py"><span class="label label-info">request.py</span></a></p>
|
||||
<h1 id="requests">Requests</h1>
|
||||
<blockquote>
|
||||
<p>If you're doing REST-based web service stuff ... you should ignore request.POST.</p>
|
||||
|
|
@ -137,14 +137,14 @@
|
|||
<h2 id="parsers">.parsers</h2>
|
||||
<p><code>request.parsers</code> should be set to a list of <code>Parser</code> instances that can be used to parse the content of the request body.</p>
|
||||
<p><code>request.parsers</code> may no longer be altered once <code>request.DATA</code>, <code>request.FILES</code> or <code>request.POST</code> have been accessed.</p>
|
||||
<p>If you're using the <code>djangorestframework.views.View</code> class... <strong>[TODO]</strong></p>
|
||||
<p>If you're using the <code>rest_framework.views.View</code> class... <strong>[TODO]</strong></p>
|
||||
<h2 id="stream">.stream</h2>
|
||||
<p><code>request.stream</code> returns a stream representing the content of the request body.</p>
|
||||
<p>You will not typically need to access <code>request.stream</code>, unless you're writing a <code>Parser</code> class.</p>
|
||||
<h2 id="authentication">.authentication</h2>
|
||||
<p><code>request.authentication</code> should be set to a list of <code>Authentication</code> instances that can be used to authenticate the request.</p>
|
||||
<p><code>request.authentication</code> may no longer be altered once <code>request.user</code> or <code>request.auth</code> have been accessed.</p>
|
||||
<p>If you're using the <code>djangorestframework.views.View</code> class... <strong>[TODO]</strong></p>
|
||||
<p>If you're using the <code>rest_framework.views.View</code> class... <strong>[TODO]</strong></p>
|
||||
</div><!--/span-->
|
||||
</div><!--/row-->
|
||||
</div><!--/.fluid-container-->
|
||||
|
|
|
|||
|
|
@ -104,7 +104,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/response.py"><span class="label label-info">response.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/response.py"><span class="label label-info">response.py</span></a></p>
|
||||
<h1 id="responses">Responses</h1>
|
||||
<blockquote>
|
||||
<p>Unlike basic HttpResponse objects, TemplateResponse objects retain the details of the context that was provided by the view to compute the response. The final output of the response is not computed until it is needed, later in the response process.</p>
|
||||
|
|
|
|||
|
|
@ -102,7 +102,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/reverse.py"><span class="label label-info">reverse.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/reverse.py"><span class="label label-info">reverse.py</span></a></p>
|
||||
<h1 id="returning-urls">Returning URLs</h1>
|
||||
<blockquote>
|
||||
<p>The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components.</p>
|
||||
|
|
@ -120,8 +120,8 @@
|
|||
<p>There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink it's output for you, which makes browsing the API much easier.</p>
|
||||
<h2 id="reverseviewname-request-args-kwargs">reverse(viewname, request, <em>args, </em>*kwargs)</h2>
|
||||
<p>Has the same behavior as <a href="https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse"><code>django.core.urlresolvers.reverse</code></a>, except that it returns a fully qualified URL, using the request to determine the host and port.</p>
|
||||
<pre class="prettyprint lang-py"><code>from djangorestframework.utils import reverse
|
||||
from djangorestframework.views import APIView
|
||||
<pre class="prettyprint lang-py"><code>from rest_framework.utils import reverse
|
||||
from rest_framework.views import APIView
|
||||
|
||||
class MyView(APIView):
|
||||
def get(self, request):
|
||||
|
|
|
|||
|
|
@ -112,7 +112,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/serializers.py"><span class="label label-info">serializers.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/serializers.py"><span class="label label-info">serializers.py</span></a></p>
|
||||
<h1 id="serializers">Serializers</h1>
|
||||
<blockquote>
|
||||
<p>Expanding the usefulness of the serializers is something that we would
|
||||
|
|
|
|||
|
|
@ -115,27 +115,27 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/settings.py"><span class="label label-info">settings.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/settings.py"><span class="label label-info">settings.py</span></a></p>
|
||||
<h1 id="settings">Settings</h1>
|
||||
<blockquote>
|
||||
<p>Namespaces are one honking great idea - let's do more of those!</p>
|
||||
<p>— <a href="http://www.python.org/dev/peps/pep-0020/">The Zen of Python</a></p>
|
||||
</blockquote>
|
||||
<p>Configuration for REST framework is all namespaced inside a single Django setting, named <code>API_SETTINGS</code>.</p>
|
||||
<p>Configuration for REST framework is all namespaced inside a single Django setting, named <code>REST_FRAMEWORK</code>.</p>
|
||||
<p>For example your project's <code>settings.py</code> file might include something like this:</p>
|
||||
<pre class="prettyprint lang-py"><code>API_SETTINGS = {
|
||||
<pre class="prettyprint lang-py"><code>REST_FRAMEWORK = {
|
||||
'DEFAULT_RENDERERS': (
|
||||
'djangorestframework.renderers.YAMLRenderer',
|
||||
'rest_framework.renderers.YAMLRenderer',
|
||||
)
|
||||
'DEFAULT_PARSERS': (
|
||||
'djangorestframework.parsers.YAMLParser',
|
||||
'rest_framework.parsers.YAMLParser',
|
||||
)
|
||||
}
|
||||
</code></pre>
|
||||
<h2 id="accessing-settings">Accessing settings</h2>
|
||||
<p>If you need to access the values of REST framework's API settings in your project,
|
||||
you should use the <code>api_settings</code> object. For example.</p>
|
||||
<pre class="prettyprint lang-py"><code>from djangorestframework.settings import api_settings
|
||||
<pre class="prettyprint lang-py"><code>from rest_framework.settings import api_settings
|
||||
|
||||
print api_settings.DEFAULT_AUTHENTICATION
|
||||
</code></pre>
|
||||
|
|
@ -144,25 +144,25 @@ print api_settings.DEFAULT_AUTHENTICATION
|
|||
<p>A list or tuple of renderer classes, that determines the default set of renderers that may be used when returning a <code>Response</code> object.</p>
|
||||
<p>Default:</p>
|
||||
<pre class="prettyprint lang-py"><code>(
|
||||
'djangorestframework.renderers.JSONRenderer',
|
||||
'djangorestframework.renderers.DocumentingHTMLRenderer'
|
||||
'djangorestframework.renderers.TemplateHTMLRenderer'
|
||||
'rest_framework.renderers.JSONRenderer',
|
||||
'rest_framework.renderers.DocumentingHTMLRenderer'
|
||||
'rest_framework.renderers.TemplateHTMLRenderer'
|
||||
)
|
||||
</code></pre>
|
||||
<h2 id="default_parsers">DEFAULT_PARSERS</h2>
|
||||
<p>A list or tuple of parser classes, that determines the default set of parsers used when accessing the <code>request.DATA</code> property.</p>
|
||||
<p>Default:</p>
|
||||
<pre class="prettyprint lang-py"><code>(
|
||||
'djangorestframework.parsers.JSONParser',
|
||||
'djangorestframework.parsers.FormParser'
|
||||
'rest_framework.parsers.JSONParser',
|
||||
'rest_framework.parsers.FormParser'
|
||||
)
|
||||
</code></pre>
|
||||
<h2 id="default_authentication">DEFAULT_AUTHENTICATION</h2>
|
||||
<p>A list or tuple of authentication classes, that determines the default set of authenticators used when accessing the <code>request.user</code> or <code>request.auth</code> properties.</p>
|
||||
<p>Default:</p>
|
||||
<pre class="prettyprint lang-py"><code>(
|
||||
'djangorestframework.authentication.SessionAuthentication',
|
||||
'djangorestframework.authentication.UserBasicAuthentication'
|
||||
'rest_framework.authentication.SessionAuthentication',
|
||||
'rest_framework.authentication.UserBasicAuthentication'
|
||||
)
|
||||
</code></pre>
|
||||
<h2 id="default_permissions">DEFAULT_PERMISSIONS</h2>
|
||||
|
|
@ -173,10 +173,10 @@ print api_settings.DEFAULT_AUTHENTICATION
|
|||
<p>Default: <code>()</code></p>
|
||||
<h2 id="default_model_serializer">DEFAULT_MODEL_SERIALIZER</h2>
|
||||
<p><strong>TODO</strong></p>
|
||||
<p>Default: <code>djangorestframework.serializers.ModelSerializer</code></p>
|
||||
<p>Default: <code>rest_framework.serializers.ModelSerializer</code></p>
|
||||
<h2 id="default_pagination_serializer">DEFAULT_PAGINATION_SERIALIZER</h2>
|
||||
<p><strong>TODO</strong></p>
|
||||
<p>Default: <code>djangorestframework.pagination.PaginationSerializer</code></p>
|
||||
<p>Default: <code>rest_framework.pagination.PaginationSerializer</code></p>
|
||||
<h2 id="format_suffix_kwarg">FORMAT_SUFFIX_KWARG</h2>
|
||||
<p><strong>TODO</strong></p>
|
||||
<p>Default: <code>'format'</code></p>
|
||||
|
|
|
|||
|
|
@ -105,14 +105,14 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/status.py"><span class="label label-info">status.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/status.py"><span class="label label-info">status.py</span></a></p>
|
||||
<h1 id="status-codes">Status Codes</h1>
|
||||
<blockquote>
|
||||
<p>418 I'm a teapot - Any attempt to brew coffee with a teapot should result in the error code "418 I'm a teapot". The resulting entity body MAY be short and stout.</p>
|
||||
<p>— <a href="http://www.ietf.org/rfc/rfc2324.txt">RFC 2324</a>, Hyper Text Coffee Pot Control Protocol</p>
|
||||
</blockquote>
|
||||
<p>Using bare status codes in your responses isn't recommended. REST framework includes a set of named constants that you can use to make more code more obvious and readable.</p>
|
||||
<pre class="prettyprint lang-py"><code>from djangorestframework import status
|
||||
<pre class="prettyprint lang-py"><code>from rest_framework import status
|
||||
|
||||
def empty_view(self):
|
||||
content = {'please move along': 'nothing to see here'}
|
||||
|
|
|
|||
|
|
@ -106,7 +106,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/throttling.py"><span class="label label-info">throttling.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/throttling.py"><span class="label label-info">throttling.py</span></a></p>
|
||||
<h1 id="throttling">Throttling</h1>
|
||||
<blockquote>
|
||||
<p>HTTP/1.1 420 Enhance Your Calm</p>
|
||||
|
|
@ -123,10 +123,10 @@
|
|||
If any throttle check fails an <code>exceptions.Throttled</code> exception will be raised, and the main body of the view will not run.</p>
|
||||
<h2 id="setting-the-throttling-policy">Setting the throttling policy</h2>
|
||||
<p>The default throttling policy may be set globally, using the <code>DEFAULT_THROTTLES</code> and <code>DEFAULT_THROTTLE_RATES</code> settings. For example.</p>
|
||||
<pre class="prettyprint lang-py"><code>API_SETTINGS = {
|
||||
<pre class="prettyprint lang-py"><code>REST_FRAMEWORK = {
|
||||
'DEFAULT_THROTTLES': (
|
||||
'djangorestframework.throttles.AnonThrottle',
|
||||
'djangorestframework.throttles.UserThrottle',
|
||||
'rest_framework.throttles.AnonThrottle',
|
||||
'rest_framework.throttles.UserThrottle',
|
||||
)
|
||||
'DEFAULT_THROTTLE_RATES': {
|
||||
'anon': '100/day',
|
||||
|
|
@ -178,7 +178,7 @@ class SustainedRateThrottle(UserRateThrottle):
|
|||
scope = 'sustained'
|
||||
</code></pre>
|
||||
<p>...and the following settings.</p>
|
||||
<pre class="prettyprint lang-py"><code>API_SETTINGS = {
|
||||
<pre class="prettyprint lang-py"><code>REST_FRAMEWORK = {
|
||||
'DEFAULT_THROTTLES': (
|
||||
'example.throttles.BurstRateThrottle',
|
||||
'example.throttles.SustainedRateThrottle',
|
||||
|
|
@ -207,9 +207,9 @@ class UploadView(APIView):
|
|||
...
|
||||
</code></pre>
|
||||
<p>...and the following settings.</p>
|
||||
<pre class="prettyprint lang-py"><code>API_SETTINGS = {
|
||||
<pre class="prettyprint lang-py"><code>REST_FRAMEWORK = {
|
||||
'DEFAULT_THROTTLES': (
|
||||
'djangorestframework.throttles.ScopedRateThrottle',
|
||||
'rest_framework.throttles.ScopedRateThrottle',
|
||||
)
|
||||
'DEFAULT_THROTTLE_RATES': {
|
||||
'contacts': '1000/day',
|
||||
|
|
|
|||
|
|
@ -110,7 +110,7 @@
|
|||
</div>
|
||||
|
||||
<div id="main-content" class="span9">
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/djangorestframework/views.py"><span class="label label-info">views.py</span></a></p>
|
||||
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/views.py"><span class="label label-info">views.py</span></a></p>
|
||||
<h1 id="views">Views</h1>
|
||||
<blockquote>
|
||||
<p>Django's class based views are a welcome departure from the old-style views.</p>
|
||||
|
|
|
|||
|
|
@ -140,18 +140,19 @@ cd django-rest-framework
|
|||
pip install -r requirements.txt
|
||||
pip install -r optionals.txt
|
||||
</code></pre>
|
||||
<p>Add <code>djangorestframework</code> to your <code>INSTALLED_APPS</code>.</p>
|
||||
<p>Add <code>rest_framework</code> to your <code>INSTALLED_APPS</code>.</p>
|
||||
<pre class="prettyprint lang-py"><code>INSTALLED_APPS = (
|
||||
...
|
||||
'djangorestframework',
|
||||
'rest_framework',
|
||||
)
|
||||
</code></pre>
|
||||
<p>If you're intending to use the browserable API you'll want to add REST framework's login and logout views. Add the following to your root <code>urls.py</code> file.</p>
|
||||
<pre class="prettyprint lang-py"><code>urlpatterns = patterns('',
|
||||
...
|
||||
url(r'^api-auth/', include('djangorestframework.urls', namespace='djangorestframework'))
|
||||
url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
|
||||
)
|
||||
</code></pre>
|
||||
<p>Note that the base URL can be whatever you want, but you must include <code>rest_framework.urls</code> with the <code>rest_framework</code> namespace.</p>
|
||||
<h2 id="quickstart">Quickstart</h2>
|
||||
<p><strong>TODO</strong></p>
|
||||
<h2 id="tutorial">Tutorial</h2>
|
||||
|
|
@ -199,7 +200,7 @@ pip install -r optionals.txt
|
|||
<pre class="prettyprint lang-py"><code>./mkdocs.py
|
||||
</code></pre>
|
||||
<p>Run the tests:</p>
|
||||
<pre class="prettyprint lang-py"><code>./djangorestframework/runtests/runtests.py
|
||||
<pre class="prettyprint lang-py"><code>./rest_framework/runtests/runtests.py
|
||||
</code></pre>
|
||||
<h2 id="license">License</h2>
|
||||
<p>Copyright (c) 2011-2012, Tom Christie
|
||||
|
|
|
|||
|
|
@ -106,11 +106,11 @@
|
|||
<h1 id="working-with-the-browsable-api">Working with the Browsable API</h1>
|
||||
<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>djangorestframework</code> package includes a <a href="../api-guide/reverse"><code>reverse</code></a> helper for this purpose.</p>
|
||||
<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>
|
||||
<h2 id="formats">Formats</h2>
|
||||
<p>By default, the API will return the format specified by the headers, which in the case of the browser is HTML. The format can be specified using <code>?format=</code> in the request, so you can look at the raw JSON response in a browser by adding <code>?format=json</code> to the URL. There are helpful extensions for viewing JSON in <a href="https://addons.mozilla.org/en-US/firefox/addon/jsonview/">Firefox</a> and <a href="https://chrome.google.com/webstore/detail/chklaanhfefbnpoihckbnefhakgolnmc">Chrome</a>.</p>
|
||||
<h2 id="customizing">Customizing</h2>
|
||||
<p>To customize the look-and-feel, create a template called <code>api.html</code> and add it to your project, eg: <code>templates/djangorestframework/api.html</code>, that extends the <code>djangorestframework/base.html</code> template.</p>
|
||||
<p>To customize the look-and-feel, create a template called <code>api.html</code> and add it to your project, eg: <code>templates/rest_framework/api.html</code>, that extends the <code>rest_framework/base.html</code> template.</p>
|
||||
<p>The included browsable API template is built with <a href="http://getbootstrap.com">Bootstrap (2.1.1)</a>, making it easy to customize the look-and-feel.</p>
|
||||
<h3 id="theme">Theme</h3>
|
||||
<p>To replace the theme wholesale, add a <code>bootstrap_theme</code> block to your <code>api.html</code> and insert a <code>link</code> to the desired Bootstrap theme css file. This will completely replace the included theme.</p>
|
||||
|
|
|
|||
|
|
@ -143,6 +143,7 @@
|
|||
<li>Can Yavuz - <a href="https://github.com/tschan">tschan</a></li>
|
||||
<li>Shawn Lewis - <a href="https://github.com/shawnlewis">shawnlewis</a></li>
|
||||
<li>Alec Perkins - <a href="https://github.com/alecperkins">alecperkins</a></li>
|
||||
<li>Michael Barrett - <a href="https://github.com/phobologic">phobologic</a></li>
|
||||
</ul>
|
||||
<p>Many thanks to everyone who's contributed to the project.</p>
|
||||
<h2 id="additional-thanks">Additional thanks</h2>
|
||||
|
|
|
|||
|
|
@ -145,10 +145,10 @@ cd tutorial
|
|||
}
|
||||
}
|
||||
</code></pre>
|
||||
<p>We'll also need to add our new <code>blog</code> app and the <code>djangorestframework</code> app to <code>INSTALLED_APPS</code>.</p>
|
||||
<p>We'll also need to add our new <code>blog</code> app and the <code>rest_framework</code> app to <code>INSTALLED_APPS</code>.</p>
|
||||
<pre class="prettyprint lang-py"><code>INSTALLED_APPS = (
|
||||
...
|
||||
'djangorestframework',
|
||||
'rest_framework',
|
||||
'blog'
|
||||
)
|
||||
</code></pre>
|
||||
|
|
@ -173,7 +173,7 @@ class Comment(models.Model):
|
|||
<h2 id="creating-a-serializer-class">Creating a Serializer class</h2>
|
||||
<p>We're going to create a simple Web API that we can use to edit these comment objects with. The first thing we need is a way of serializing and deserializing the objects into representations such as <code>json</code>. We do this by declaring serializers, that work very similarly to Django's forms. Create a file in the project named <code>serializers.py</code> and add the following.</p>
|
||||
<pre class="prettyprint lang-py"><code>from blog import models
|
||||
from djangorestframework import serializers
|
||||
from rest_framework import serializers
|
||||
|
||||
class CommentSerializer(serializers.Serializer):
|
||||
email = serializers.EmailField()
|
||||
|
|
@ -201,8 +201,8 @@ class CommentSerializer(serializers.Serializer):
|
|||
<p>Okay, once we've got a few imports out of the way, we'd better create a few comments to work with.</p>
|
||||
<pre class="prettyprint lang-py"><code>from blog.models import Comment
|
||||
from blog.serializers import CommentSerializer
|
||||
from djangorestframework.renderers import JSONRenderer
|
||||
from djangorestframework.parsers import JSONParser
|
||||
from rest_framework.renderers import JSONRenderer
|
||||
from rest_framework.parsers import JSONParser
|
||||
|
||||
c1 = Comment(email='leila@example.com', content='nothing to say')
|
||||
c2 = Comment(email='tom@example.com', content='foo bar')
|
||||
|
|
@ -238,8 +238,8 @@ We'll start off by creating a subclass of HttpResponse that we can use to render
|
|||
<p>Edit the <code>blog/views.py</code> file, and add the following.</p>
|
||||
<pre class="prettyprint lang-py"><code>from blog.models import Comment
|
||||
from blog.serializers import CommentSerializer
|
||||
from djangorestframework.renderers import JSONRenderer
|
||||
from djangorestframework.parsers import JSONParser
|
||||
from rest_framework.renderers import JSONRenderer
|
||||
from rest_framework.parsers import JSONParser
|
||||
from django.http import HttpResponse
|
||||
|
||||
class JSONResponse(HttpResponse):
|
||||
|
|
|
|||
|
|
@ -135,9 +135,9 @@ request.DATA # Handles arbitrary data. Works any HTTP request with content.
|
|||
<p>We don't need our <code>JSONResponse</code> class anymore, so go ahead and delete that. Once that's done we can start refactoring our views slightly.</p>
|
||||
<pre class="prettyprint lang-py"><code>from blog.models import Comment
|
||||
from blog.serializers import CommentSerializer
|
||||
from djangorestframework import status
|
||||
from djangorestframework.decorators import api_view
|
||||
from djangorestframework.response import Response
|
||||
from rest_framework import status
|
||||
from rest_framework.decorators import api_view
|
||||
from rest_framework.response import Response
|
||||
|
||||
@api_view(['GET', 'POST'])
|
||||
def comment_root(request):
|
||||
|
|
@ -198,7 +198,7 @@ def comment_instance(request, pk):
|
|||
</code></pre>
|
||||
<p>Now update the <code>urls.py</code> file slightly, to append a set of <code>format_suffix_patterns</code> in addition to the existing URLs.</p>
|
||||
<pre class="prettyprint lang-py"><code>from django.conf.urls import patterns, url
|
||||
from djangorestframework.urlpatterns import format_suffix_patterns
|
||||
from rest_framework.urlpatterns import format_suffix_patterns
|
||||
|
||||
urlpatterns = patterns('blogpost.views',
|
||||
url(r'^$', 'comment_root'),
|
||||
|
|
|
|||
|
|
@ -110,9 +110,9 @@
|
|||
<pre class="prettyprint lang-py"><code>from blog.models import Comment
|
||||
from blog.serializers import CommentSerializer
|
||||
from django.http import Http404
|
||||
from djangorestframework.views import APIView
|
||||
from djangorestframework.response import Response
|
||||
from djangorestframework import status
|
||||
from rest_framework.views import APIView
|
||||
from rest_framework.response import Response
|
||||
from rest_framework import status
|
||||
|
||||
class CommentRoot(APIView):
|
||||
"""
|
||||
|
|
@ -165,7 +165,7 @@ class CommentRoot(APIView):
|
|||
<p>That's looking good. Again, it's still pretty similar to the function based view right now.</p>
|
||||
<p>We'll also need to refactor our URLconf slightly now we're using class based views.</p>
|
||||
<pre class="prettyprint lang-py"><code>from django.conf.urls import patterns, url
|
||||
from djangorestframework.urlpatterns import format_suffix_patterns
|
||||
from rest_framework.urlpatterns import format_suffix_patterns
|
||||
from blogpost import views
|
||||
|
||||
urlpatterns = patterns('',
|
||||
|
|
@ -182,8 +182,8 @@ urlpatterns = format_suffix_patterns(urlpatterns)
|
|||
<p>Let's take a look at how we can compose our views by using the mixin classes.</p>
|
||||
<pre class="prettyprint lang-py"><code>from blog.models import Comment
|
||||
from blog.serializers import CommentSerializer
|
||||
from djangorestframework import mixins
|
||||
from djangorestframework import generics
|
||||
from rest_framework import mixins
|
||||
from rest_framework import generics
|
||||
|
||||
class CommentRoot(mixins.ListModelMixin,
|
||||
mixins.CreateModelMixin,
|
||||
|
|
@ -220,7 +220,7 @@ class CommentRoot(mixins.ListModelMixin,
|
|||
<p>Using the mixin classes we've rewritten the views to use slightly less code than before, but we can go one step further. REST framework provides a set of already mixed-in generic views that we can use.</p>
|
||||
<pre class="prettyprint lang-py"><code>from blog.models import Comment
|
||||
from blog.serializers import CommentSerializer
|
||||
from djangorestframework import generics
|
||||
from rest_framework import generics
|
||||
|
||||
class CommentRoot(generics.RootAPIView):
|
||||
model = Comment
|
||||
|
|
|
|||
|
|
@ -149,7 +149,7 @@ urlpatterns = patterns('blogpost.views',
|
|||
<h2 id="using-routers">Using Routers</h2>
|
||||
<p>Right now that hasn't really saved us a lot of code. However, now that we're using Resources rather than Views, we actually don't need to design the urlconf ourselves. The conventions for wiring up resources into views and urls can be handled automatically, using <code>Router</code> classes. All we need to do is register the appropriate resources with a router, and let it do the rest. Here's our re-wired <code>urls.py</code> file.</p>
|
||||
<pre class="prettyprint lang-py"><code>from blog import resources
|
||||
from djangorestframework.routers import DefaultRouter
|
||||
from rest_framework.routers import DefaultRouter
|
||||
|
||||
router = DefaultRouter()
|
||||
router.register(resources.BlogPostResource)
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user