mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-11-14 05:36:50 +03:00
629 lines
29 KiB
HTML
629 lines
29 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<meta charset="utf-8">
|
|
<title>The Browsable API - Django REST framework</title>
|
|
<link href="../../img/favicon.ico" rel="icon" type="image/x-icon">
|
|
<link rel="canonical" href="https://www.django-rest-framework.org/topics/browsable-api/" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="description" content="Django, API, REST, The Browsable API">
|
|
<meta name="author" content="Tom Christie">
|
|
|
|
<!-- Le styles -->
|
|
<link href="../../css/prettify.css" rel="stylesheet">
|
|
<link href="../../css/bootstrap.css" rel="stylesheet">
|
|
<link href="../../css/bootstrap-responsive.css" rel="stylesheet">
|
|
<link href="../../css/default.css" rel="stylesheet">
|
|
|
|
|
|
<script type="text/javascript">
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-18852272-2']);
|
|
_gaq.push(['_trackPageview']);
|
|
|
|
(function() {
|
|
var ga = document.createElement('script');
|
|
ga.type = 'text/javascript';
|
|
ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0];
|
|
s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
</script>
|
|
|
|
<style>
|
|
#sidebarInclude img {
|
|
margin-bottom: 10px;
|
|
}
|
|
#sidebarInclude a.promo {
|
|
color: black;
|
|
}
|
|
@media (max-width: 767px) {
|
|
div.promo {
|
|
display: none;
|
|
}
|
|
}
|
|
</style>
|
|
</head>
|
|
<body onload="prettyPrint()" class="-page">
|
|
|
|
<div class="wrapper">
|
|
<div class="navbar navbar-inverse navbar-fixed-top">
|
|
<div class="navbar-inner">
|
|
<div class="container-fluid">
|
|
<a class="repo-link btn btn-primary btn-small" href="https://github.com/encode/django-rest-framework/tree/master">GitHub</a>
|
|
<a class="repo-link btn btn-inverse btn-small " rel="next" href="../rest-hypermedia-hateoas/">
|
|
Next <i class="icon-arrow-right icon-white"></i>
|
|
</a>
|
|
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../browser-enhancements/">
|
|
<i class="icon-arrow-left icon-white"></i> Previous
|
|
</a>
|
|
<a id="search_modal_show" class="repo-link btn btn-inverse btn-small" href="#mkdocs_search_modal" data-toggle="modal" data-target="#mkdocs_search_modal"><i class="icon-search icon-white"></i> Search</a>
|
|
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
</a>
|
|
<a class="brand" href="https://www.django-rest-framework.org/">Django REST framework</a>
|
|
<div class="nav-collapse collapse">
|
|
|
|
<!-- Main navigation -->
|
|
<ul class="nav navbar-nav">
|
|
|
|
<li >
|
|
<a href="../..">Home</a>
|
|
</li>
|
|
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorial <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
<li >
|
|
<a href="../../tutorial/quickstart/">Quickstart</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/1-serialization/">1 - Serialization</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/2-requests-and-responses/">2 - Requests and responses</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/3-class-based-views/">3 - Class based views</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/4-authentication-and-permissions/">4 - Authentication and permissions</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/5-relationships-and-hyperlinked-apis/">5 - Relationships and hyperlinked APIs</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../tutorial/6-viewsets-and-routers/">6 - Viewsets and routers</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Guide <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
<li >
|
|
<a href="../../api-guide/requests/">Requests</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/responses/">Responses</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/views/">Views</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/generic-views/">Generic views</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/viewsets/">Viewsets</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/routers/">Routers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/parsers/">Parsers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/renderers/">Renderers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/serializers/">Serializers</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/fields/">Serializer fields</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/relations/">Serializer relations</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/validators/">Validators</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/authentication/">Authentication</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/permissions/">Permissions</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/caching/">Caching</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/throttling/">Throttling</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/filtering/">Filtering</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/pagination/">Pagination</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/versioning/">Versioning</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/content-negotiation/">Content negotiation</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/metadata/">Metadata</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/schemas/">Schemas</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/format-suffixes/">Format suffixes</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/reverse/">Returning URLs</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/exceptions/">Exceptions</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/status-codes/">Status codes</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/testing/">Testing</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../api-guide/settings/">Settings</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
<li class="dropdown active">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Topics <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
<li >
|
|
<a href="../documenting-your-api/">Documenting your API</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../internationalization/">Internationalization</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../ajax-csrf-cors/">AJAX, CSRF & CORS</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../html-and-forms/">HTML & Forms</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../browser-enhancements/">Browser Enhancements</a>
|
|
</li>
|
|
|
|
<li class="active" >
|
|
<a href="./">The Browsable API</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../rest-hypermedia-hateoas/">REST, Hypermedia & HATEOAS</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Community <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
<li >
|
|
<a href="../../community/tutorials-and-resources/">Tutorials and Resources</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/third-party-packages/">Third Party Packages</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/contributing/">Contributing to REST framework</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/project-management/">Project management</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/release-notes/">Release Notes</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.15-announcement/">3.15 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.14-announcement/">3.14 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.13-announcement/">3.13 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.12-announcement/">3.12 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.11-announcement/">3.11 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.10-announcement/">3.10 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.9-announcement/">3.9 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.8-announcement/">3.8 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.7-announcement/">3.7 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.6-announcement/">3.6 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.5-announcement/">3.5 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.4-announcement/">3.4 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.3-announcement/">3.3 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.2-announcement/">3.2 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.1-announcement/">3.1 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/3.0-announcement/">3.0 Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/kickstarter-announcement/">Kickstarter Announcement</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/mozilla-grant/">Mozilla Grant</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/funding/">Funding</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="../../community/jobs/">Jobs</a>
|
|
</li>
|
|
|
|
</ul>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
</div>
|
|
<!--/.nav-collapse -->
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="body-content">
|
|
<div class="container-fluid">
|
|
<!-- Search Modal -->
|
|
<div id="mkdocs_search_modal" class="modal hide fade" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true">
|
|
<div class="modal-header">
|
|
<button type="button" class="close" data-dismiss="modal" aria-hidden="true">×</button>
|
|
<h3 id="myModalLabel">Documentation search</h3>
|
|
</div>
|
|
|
|
<div class="modal-body">
|
|
<form role="form" autocomplete="off">
|
|
<div class="form-group">
|
|
<input type="text" name="q" class="form-control" placeholder="Search..." id="mkdocs-search-query">
|
|
</div>
|
|
</form>
|
|
<div id="mkdocs-search-results"></div>
|
|
</div>
|
|
|
|
<div class="modal-footer">
|
|
<button class="btn" data-dismiss="modal" aria-hidden="true">Close</button>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="row-fluid">
|
|
<div class="span3">
|
|
<div id="table-of-contents">
|
|
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
|
|
|
|
|
|
|
|
<li class="main">
|
|
<a href="#the-browsable-api">The Browsable API</a>
|
|
</li>
|
|
|
|
|
|
<li>
|
|
<a href="#urls">URLs</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#formats">Formats</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#authentication">Authentication</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#customizing">Customizing</a>
|
|
</li>
|
|
|
|
|
|
|
|
<div class="promo">
|
|
<hr/>
|
|
<div id="sidebarInclude">
|
|
</div>
|
|
</ul>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="main-content" class="span9">
|
|
|
|
|
|
|
|
<h1 id="the-browsable-api"><a class="toclink" href="#the-browsable-api">The Browsable API</a></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>— <a href="https://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"><a class="toclink" href="#urls">URLs</a></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>
|
|
<h2 id="formats"><a class="toclink" href="#formats">Formats</a></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="authentication"><a class="toclink" href="#authentication">Authentication</a></h2>
|
|
<p>To quickly add authentication to the browesable api, add a routes named <code>"login"</code> and <code>"logout"</code> under the namespace <code>"rest_framework"</code>. DRF provides default routes for this which you can add to your urlconf:</p>
|
|
<pre><code class="language-python">urlpatterns = [
|
|
# ...
|
|
url(r"^api-auth/", include("rest_framework.urls", namespace="rest_framework"))
|
|
]
|
|
</code></pre>
|
|
<h2 id="customizing"><a class="toclink" href="#customizing">Customizing</a></h2>
|
|
<p>The browsable API is built with <a href="https://getbootstrap.com/">Twitter's Bootstrap</a> (v 3.4.1), making it easy to customize the look-and-feel.</p>
|
|
<p>To customize the default style, create a template called <code>rest_framework/api.html</code> that extends from <code>rest_framework/base.html</code>. For example:</p>
|
|
<p><strong>templates/rest_framework/api.html</strong></p>
|
|
<pre><code>{% extends "rest_framework/base.html" %}
|
|
|
|
... # Override blocks with required customizations
|
|
</code></pre>
|
|
<h3 id="overriding-the-default-theme"><a class="toclink" href="#overriding-the-default-theme">Overriding the default theme</a></h3>
|
|
<p>To replace the default theme, 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>
|
|
<pre><code>{% block bootstrap_theme %}
|
|
<link rel="stylesheet" href="/path/to/my/bootstrap.css" type="text/css">
|
|
{% endblock %}
|
|
</code></pre>
|
|
<p>Suitable pre-made replacement themes are available at <a href="https://bootswatch.com/">Bootswatch</a>. To use any of the Bootswatch themes, simply download the theme's <code>bootstrap.min.css</code> file, add it to your project, and replace the default one as described above. Make sure that the Bootstrap version of the new theme matches that of the default theme.</p>
|
|
<p>You can also change the navbar variant, which by default is <code>navbar-inverse</code>, using the <code>bootstrap_navbar_variant</code> block. The empty <code>{% block bootstrap_navbar_variant %}{% endblock %}</code> will use the original Bootstrap navbar style.</p>
|
|
<p>Full example:</p>
|
|
<pre><code>{% extends "rest_framework/base.html" %}
|
|
|
|
{% block bootstrap_theme %}
|
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootswatch@3.4.1/flatly/bootstrap.min.css" type="text/css">
|
|
{% endblock %}
|
|
|
|
{% block bootstrap_navbar_variant %}{% endblock %}
|
|
</code></pre>
|
|
<p>For more specific CSS tweaks than simply overriding the default bootstrap theme you can override the <code>style</code> block.</p>
|
|
<hr />
|
|
<p><img alt="Cerulean theme" src="../../img/cerulean.png" /></p>
|
|
<p><em>Screenshot of the bootswatch 'Cerulean' theme</em></p>
|
|
<hr />
|
|
<p><img alt="Slate theme" src="../../img/slate.png" /></p>
|
|
<p><em>Screenshot of the bootswatch 'Slate' theme</em></p>
|
|
<hr />
|
|
<h3 id="third-party-packages-for-customization"><a class="toclink" href="#third-party-packages-for-customization">Third party packages for customization</a></h3>
|
|
<p>You can use a third party package for customization, rather than doing it by yourself. Here is 2 packages for customizing the API:</p>
|
|
<ul>
|
|
<li><a href="https://github.com/youzarsiph/rest-framework-redesign">rest-framework-redesign</a> - A package for customizing the API using Bootstrap 5. Modern and sleek design, it comes with the support for dark mode.</li>
|
|
<li><a href="https://github.com/youzarsiph/rest-framework-material">rest-framework-material</a> - Material design for Django REST Framework.</li>
|
|
</ul>
|
|
<hr />
|
|
<p><img alt="Django REST Framework Redesign" src="../../img/rfr.png" /></p>
|
|
<p><em>Screenshot of the rest-framework-redesign</em></p>
|
|
<hr />
|
|
<p><img alt="Django REST Framework Material" src="../../img/rfm.png" /></p>
|
|
<p><em>Screenshot of the rest-framework-material</em></p>
|
|
<hr />
|
|
<h3 id="blocks"><a class="toclink" href="#blocks">Blocks</a></h3>
|
|
<p>All of the blocks available in the browsable API base template that can be used in your <code>api.html</code>.</p>
|
|
<ul>
|
|
<li><code>body</code> - The entire html <code><body></code>.</li>
|
|
<li><code>bodyclass</code> - Class attribute for the <code><body></code> tag, empty by default.</li>
|
|
<li><code>bootstrap_theme</code> - CSS for the Bootstrap theme.</li>
|
|
<li><code>bootstrap_navbar_variant</code> - CSS class for the navbar.</li>
|
|
<li><code>branding</code> - Branding section of the navbar, see <a href="https://getbootstrap.com/2.3.2/components.html#navbar">Bootstrap components</a>.</li>
|
|
<li><code>breadcrumbs</code> - Links showing resource nesting, allowing the user to go back up the resources. It's recommended to preserve these, but they can be overridden using the breadcrumbs block.</li>
|
|
<li><code>script</code> - JavaScript files for the page.</li>
|
|
<li><code>style</code> - CSS stylesheets for the page.</li>
|
|
<li><code>title</code> - Title of the page.</li>
|
|
<li><code>userlinks</code> - This is a list of links on the right of the header, by default containing login/logout links. To add links instead of replace, use <code>{{ block.super }}</code> to preserve the authentication links.</li>
|
|
</ul>
|
|
<h4 id="components"><a class="toclink" href="#components">Components</a></h4>
|
|
<p>All of the standard <a href="https://getbootstrap.com/2.3.2/components.html">Bootstrap components</a> are available.</p>
|
|
<h4 id="tooltips"><a class="toclink" href="#tooltips">Tooltips</a></h4>
|
|
<p>The browsable API makes use of the Bootstrap tooltips component. Any element with the <code>js-tooltip</code> class and a <code>title</code> attribute has that title content will display a tooltip on hover events.</p>
|
|
<h3 id="login-template"><a class="toclink" href="#login-template">Login Template</a></h3>
|
|
<p>To add branding and customize the look-and-feel of the login template, create a template called <code>login.html</code> and add it to your project, eg: <code>templates/rest_framework/login.html</code>. The template should extend from <code>rest_framework/login_base.html</code>.</p>
|
|
<p>You can add your site name or branding by including the branding block:</p>
|
|
<pre><code>{% extends "rest_framework/login_base.html" %}
|
|
|
|
{% block branding %}
|
|
<h3 style="margin: 0 0 20px;">My Site Name</h3>
|
|
{% endblock %}
|
|
</code></pre>
|
|
<p>You can also customize the style by adding the <code>bootstrap_theme</code> or <code>style</code> block similar to <code>api.html</code>.</p>
|
|
<h3 id="advanced-customization"><a class="toclink" href="#advanced-customization">Advanced Customization</a></h3>
|
|
<h4 id="context"><a class="toclink" href="#context">Context</a></h4>
|
|
<p>The context that's available to the template:</p>
|
|
<ul>
|
|
<li><code>allowed_methods</code> : A list of methods allowed by the resource</li>
|
|
<li><code>api_settings</code> : The API settings</li>
|
|
<li><code>available_formats</code> : A list of formats allowed by the resource</li>
|
|
<li><code>breadcrumblist</code> : The list of links following the chain of nested resources</li>
|
|
<li><code>content</code> : The content of the API response</li>
|
|
<li><code>description</code> : The description of the resource, generated from its docstring</li>
|
|
<li><code>name</code> : The name of the resource</li>
|
|
<li><code>post_form</code> : A form instance for use by the POST form (if allowed)</li>
|
|
<li><code>put_form</code> : A form instance for use by the PUT form (if allowed)</li>
|
|
<li><code>display_edit_forms</code> : A boolean indicating whether or not POST, PUT and PATCH forms will be displayed</li>
|
|
<li><code>request</code> : The request object</li>
|
|
<li><code>response</code> : The response object</li>
|
|
<li><code>version</code> : The version of Django REST Framework</li>
|
|
<li><code>view</code> : The view handling the request</li>
|
|
<li><code>FORMAT_PARAM</code> : The view can accept a format override</li>
|
|
<li><code>METHOD_PARAM</code> : The view can accept a method override</li>
|
|
</ul>
|
|
<p>You can override the <code>BrowsableAPIRenderer.get_context()</code> method to customise the context that gets passed to the template.</p>
|
|
<h4 id="not-using-basehtml"><a class="toclink" href="#not-using-basehtml">Not using base.html</a></h4>
|
|
<p>For more advanced customization, such as not having a Bootstrap basis or tighter integration with the rest of your site, you can simply choose not to have <code>api.html</code> extend <code>base.html</code>. Then the page content and capabilities are entirely up to you.</p>
|
|
<h4 id="handling-choicefield-with-large-numbers-of-items"><a class="toclink" href="#handling-choicefield-with-large-numbers-of-items">Handling <code>ChoiceField</code> with large numbers of items.</a></h4>
|
|
<p>When a relationship or <code>ChoiceField</code> has too many items, rendering the widget containing all the options can become very slow, and cause the browsable API rendering to perform poorly.</p>
|
|
<p>The simplest option in this case is to replace the select input with a standard text input. For example:</p>
|
|
<pre><code> author = serializers.HyperlinkedRelatedField(
|
|
queryset=User.objects.all(),
|
|
style={'base_template': 'input.html'}
|
|
)
|
|
</code></pre>
|
|
<h4 id="autocomplete"><a class="toclink" href="#autocomplete">Autocomplete</a></h4>
|
|
<p>An alternative, but more complex option would be to replace the input with an autocomplete widget, that only loads and renders a subset of the available options as needed. If you need to do this you'll need to do some work to build a custom autocomplete HTML template yourself.</p>
|
|
<p>There are <a href="https://www.djangopackages.com/grids/g/auto-complete/">a variety of packages for autocomplete widgets</a>, such as <a href="https://github.com/yourlabs/django-autocomplete-light">django-autocomplete-light</a>, that you may want to refer to. Note that you will not be able to simply include these components as standard widgets, but will need to write the HTML template explicitly. This is because REST framework 3.0 no longer supports the <code>widget</code> keyword argument since it now uses templated HTML generation.</p>
|
|
<hr />
|
|
|
|
|
|
</div> <!--/span-->
|
|
</div> <!--/row-->
|
|
</div> <!--/.fluid-container-->
|
|
</div> <!--/.body content-->
|
|
<div id="push"></div>
|
|
</div> <!--/.wrapper -->
|
|
|
|
<footer class="span12">
|
|
<p>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.
|
|
</p>
|
|
</footer>
|
|
|
|
<!-- Le javascript
|
|
================================================== -->
|
|
<!-- Placed at the end of the document so the pages load faster -->
|
|
<script async src="https://fund.django-rest-framework.org/sidebar_include.js"></script>
|
|
<script src="../../js/jquery-1.8.1-min.js"></script>
|
|
<script src="../../js/prettify-1.0.js"></script>
|
|
<script src="../../js/bootstrap-2.1.1-min.js"></script>
|
|
<script src="../../js/theme.js"></script>
|
|
|
|
<script>var base_url = '../..';</script>
|
|
|
|
<script src="../../search/main.js" defer></script>
|
|
|
|
|
|
<script>
|
|
var shiftWindow = function() {
|
|
scrollBy(0, -50)
|
|
};
|
|
|
|
if (location.hash) shiftWindow();
|
|
window.addEventListener("hashchange", shiftWindow);
|
|
|
|
$('.dropdown-menu').on('click touchstart', function(event) {
|
|
event.stopPropagation();
|
|
});
|
|
|
|
// Dynamically force sidenav/dropdown to no higher than browser window
|
|
$('.side-nav, .dropdown-menu').css('max-height', window.innerHeight - 130);
|
|
|
|
$(function() {
|
|
$(window).resize(function() {
|
|
$('.side-nav, .dropdown-menu').css('max-height', window.innerHeight - 130);
|
|
});
|
|
});
|
|
</script>
|
|
</body>
|
|
|
|
</html> |