mirror of
https://github.com/encode/django-rest-framework.git
synced 2025-10-31 16:07:38 +03:00
742 lines
31 KiB
HTML
742 lines
31 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<meta charset="utf-8">
|
|
<title>Home - 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/" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="description" content="Django, API, REST, Home">
|
|
<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="index-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">GitHub</a>
|
|
<a class="repo-link btn btn-inverse btn-small " rel="next" href="tutorial/quickstart/">
|
|
Next <i class="icon-arrow-right icon-white"></i>
|
|
</a>
|
|
<a class="repo-link btn btn-inverse btn-small disabled" rel="prev" >
|
|
<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 class="active" >
|
|
<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">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Topics <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
|
|
<li >
|
|
<a href="topics/documenting-your-api/">Documenting your API</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="topics/internationalization/">Internationalization</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="topics/ajax-csrf-cors/">AJAX, CSRF & CORS</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="topics/html-and-forms/">HTML & Forms</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="topics/browser-enhancements/">Browser Enhancements</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="topics/browsable-api/">The Browsable API</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="topics/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.16-announcement/">3.16 Announcement</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="#">Django REST framework</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="">
|
|
<a href="#funding">Funding</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="">
|
|
<a href="#requirements">Requirements</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="">
|
|
<a href="#installation">Installation</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="">
|
|
<a href="#example">Example</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="">
|
|
<a href="#quickstart">Quickstart</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="">
|
|
<a href="#development">Development</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="">
|
|
<a href="#support">Support</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="">
|
|
<a href="#security">Security</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="">
|
|
<a href="#license">License</a>
|
|
</li>
|
|
|
|
|
|
|
|
|
|
<div class="promo">
|
|
<hr/>
|
|
<div id="sidebarInclude">
|
|
</div>
|
|
</ul>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="main-content" class="span9">
|
|
|
|
|
|
|
|
<style>
|
|
.promo li a {
|
|
float: left;
|
|
width: 130px;
|
|
height: 20px;
|
|
text-align: center;
|
|
margin: 10px 30px;
|
|
padding: 150px 0 0 0;
|
|
background-position: 0 50%;
|
|
background-size: 130px auto;
|
|
background-repeat: no-repeat;
|
|
font-size: 120%;
|
|
color: black;
|
|
}
|
|
.promo li {
|
|
list-style: none;
|
|
}
|
|
</style>
|
|
|
|
<p class="badges" height=20px>
|
|
<iframe src="https://ghbtns.com/github-btn.html?user=encode&repo=django-rest-framework&type=watch&count=true" class="github-star-button" allowtransparency="true" frameborder="0" scrolling="0" width="110px" height="20px"></iframe>
|
|
|
|
<a href="https://github.com/encode/django-rest-framework/actions/workflows/main.yml">
|
|
<img src="https://github.com/encode/django-rest-framework/actions/workflows/main.yml/badge.svg" class="status-badge">
|
|
</a>
|
|
|
|
<a href="https://pypi.org/project/djangorestframework/">
|
|
<img src="https://img.shields.io/pypi/v/djangorestframework.svg" class="status-badge">
|
|
</a>
|
|
</p>
|
|
|
|
<hr />
|
|
<p>
|
|
<h1 style="position: absolute;
|
|
width: 1px;
|
|
height: 1px;
|
|
padding: 0;
|
|
margin: -1px;
|
|
overflow: hidden;
|
|
clip: rect(0,0,0,0);
|
|
border: 0;">Django REST Framework</h1>
|
|
|
|
<img alt="Django REST Framework" title="Logo by Jake 'Sid' Smith" src="img/logo.png" width="600px" style="display: block; margin: 0 auto 0 auto">
|
|
</p>
|
|
|
|
<p>Django REST framework is a powerful and flexible toolkit for building Web APIs.</p>
|
|
<p>Some reasons you might want to use REST framework:</p>
|
|
<ul>
|
|
<li>The Web browsable API is a huge usability win for your developers.</li>
|
|
<li><a href="api-guide/authentication/">Authentication policies</a> including packages for <a href="api-guide/authentication/#django-rest-framework-oauth">OAuth1a</a> and <a href="api-guide/authentication/#django-oauth-toolkit">OAuth2</a>.</li>
|
|
<li><a href="api-guide/serializers/">Serialization</a> that supports both <a href="api-guide/serializers#modelserializer">ORM</a> and <a href="api-guide/serializers#serializers">non-ORM</a> data sources.</li>
|
|
<li>Customizable all the way down - just use <a href="api-guide/views#function-based-views">regular function-based views</a> if you don't need the <a href="api-guide/generic-views/">more</a> <a href="api-guide/viewsets/">powerful</a> <a href="api-guide/routers/">features</a>.</li>
|
|
<li>Extensive documentation, and <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">great community support</a>.</li>
|
|
<li>Used and trusted by internationally recognized companies including <a href="https://www.mozilla.org/en-US/about/">Mozilla</a>, <a href="https://www.redhat.com/">Red Hat</a>, <a href="https://www.heroku.com/">Heroku</a>, and <a href="https://www.eventbrite.co.uk/about/">Eventbrite</a>.</li>
|
|
</ul>
|
|
<hr />
|
|
<h2 id="funding"><a class="toclink" href="#funding">Funding</a></h2>
|
|
<p>REST framework is a <em>collaboratively funded project</em>. If you use
|
|
REST framework commercially we strongly encourage you to invest in its
|
|
continued development by <strong><a href="community/funding/">signing up for a paid plan</a></strong>.</p>
|
|
<p><em>Every single sign-up helps us make REST framework long-term financially sustainable.</em></p>
|
|
<ul class="premium-promo promo">
|
|
<li><a href="https://getsentry.com/welcome/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/sentry130.png)">Sentry</a></li>
|
|
<li><a href="https://getstream.io/?utm_source=DjangoRESTFramework&utm_medium=Webpage_Logo_Ad&utm_content=Developer&utm_campaign=DjangoRESTFramework_Jan2022_HomePage" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/stream-130.png)">Stream</a></li>
|
|
<li><a href="https://www.spacinov.com/" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/spacinov.png)">Spacinov</a></li>
|
|
<li><a href="https://retool.com/?utm_source=djangorest&utm_medium=sponsorship" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/retool-sidebar.png)">Retool</a></li>
|
|
<li><a href="https://bit.io/jobs?utm_source=DRF&utm_medium=sponsor&utm_campaign=DRF_sponsorship" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/bitio_logo_gold_background.png)">bit.io</a></li>
|
|
<li><a href="https://posthog.com?utm_source=DRF&utm_medium=sponsor&utm_campaign=DRF_sponsorship" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/135996800-d49fe024-32d9-441a-98d9-4c7596287a67.png)">PostHog</a></li>
|
|
<li><a href="https://cryptapi.io" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/cryptapi.png)">CryptAPI</a></li>
|
|
<li><a href="https://www.fezto.xyz/?utm_source=DjangoRESTFramework" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/fezto.png)">FEZTO</a></li>
|
|
<li><a href="https://www.svix.com/?utm_source=django-REST&utm_medium=sponsorship" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/svix.png)">Svix</a></li>
|
|
<li><a href="https://zuplo.link/django-web" style="background-image: url(https://fund-rest-framework.s3.amazonaws.com/zuplo.png)">Zuplo</a></li>
|
|
</ul>
|
|
<div style="clear: both; padding-bottom: 20px;"></div>
|
|
|
|
<p><em>Many thanks to all our <a href="https://fund.django-rest-framework.org/topics/funding/#our-sponsors">wonderful sponsors</a>, and in particular to our premium backers, <a href="https://getsentry.com/welcome/">Sentry</a>, <a href="https://getstream.io/?utm_source=DjangoRESTFramework&utm_medium=Webpage_Logo_Ad&utm_content=Developer&utm_campaign=DjangoRESTFramework_Jan2022_HomePage">Stream</a>, <a href="https://www.spacinov.com/">Spacinov</a>, <a href="https://retool.com/?utm_source=djangorest&utm_medium=sponsorship">Retool</a>, <a href="https://bit.io/jobs?utm_source=DRF&utm_medium=sponsor&utm_campaign=DRF_sponsorship">bit.io</a>, <a href="https://posthog.com?utm_source=DRF&utm_medium=sponsor&utm_campaign=DRF_sponsorship">PostHog</a>, <a href="https://cryptapi.io">CryptAPI</a>, <a href="https://www.fezto.xyz/?utm_source=DjangoRESTFramework">FEZTO</a>, <a href="https://www.svix.com/?utm_source=django-REST&utm_medium=sponsorship">Svix</a>, , and <a href="https://zuplo.link/django-web">Zuplo</a>.</em></p>
|
|
<hr />
|
|
<h2 id="requirements"><a class="toclink" href="#requirements">Requirements</a></h2>
|
|
<p>REST framework requires the following:</p>
|
|
<ul>
|
|
<li>Django (4.2, 5.0, 5.1, 5.2)</li>
|
|
<li>Python (3.10, 3.11, 3.12, 3.13, 3.14)</li>
|
|
</ul>
|
|
<p>We <strong>highly recommend</strong> and only officially support the latest patch release of
|
|
each Python and Django series.</p>
|
|
<p>The following packages are optional:</p>
|
|
<ul>
|
|
<li><a href="https://pypi.org/project/PyYAML/">PyYAML</a>, <a href="https://pypi.org/project/uritemplate/">uritemplate</a> (5.1+, 3.0.0+) - Schema generation support.</li>
|
|
<li><a href="https://pypi.org/project/Markdown/">Markdown</a> (3.3.0+) - Markdown support for the browsable API.</li>
|
|
<li><a href="https://pypi.org/project/Pygments/">Pygments</a> (2.7.0+) - Add syntax highlighting to Markdown processing.</li>
|
|
<li><a href="https://pypi.org/project/django-filter/">django-filter</a> (1.0.1+) - Filtering support.</li>
|
|
<li><a href="https://github.com/django-guardian/django-guardian">django-guardian</a> (1.1.1+) - Object level permissions support.</li>
|
|
</ul>
|
|
<h2 id="installation"><a class="toclink" href="#installation">Installation</a></h2>
|
|
<p>Install using <code>pip</code>, including any optional packages you want...</p>
|
|
<pre><code>pip install djangorestframework
|
|
pip install markdown # Markdown support for the browsable API.
|
|
pip install django-filter # Filtering support
|
|
</code></pre>
|
|
<p>...or clone the project from github.</p>
|
|
<pre><code>git clone https://github.com/encode/django-rest-framework
|
|
</code></pre>
|
|
<p>Add <code>'rest_framework'</code> to your <code>INSTALLED_APPS</code> setting.</p>
|
|
<pre><code>INSTALLED_APPS = [
|
|
...
|
|
'rest_framework',
|
|
]
|
|
</code></pre>
|
|
<p>If you're intending to use the browsable API you'll probably also want to add REST framework's login and logout views. Add the following to your root <code>urls.py</code> file.</p>
|
|
<pre><code>urlpatterns = [
|
|
...
|
|
path('api-auth/', include('rest_framework.urls'))
|
|
]
|
|
</code></pre>
|
|
<p>Note that the URL path can be whatever you want.</p>
|
|
<h2 id="example"><a class="toclink" href="#example">Example</a></h2>
|
|
<p>Let's take a look at a quick example of using REST framework to build a simple model-backed API.</p>
|
|
<p>We'll create a read-write API for accessing information on the users of our project.</p>
|
|
<p>Any global settings for a REST framework API are kept in a single configuration dictionary named <code>REST_FRAMEWORK</code>. Start off by adding the following to your <code>settings.py</code> module:</p>
|
|
<pre><code>REST_FRAMEWORK = {
|
|
# Use Django's standard `django.contrib.auth` permissions,
|
|
# or allow read-only access for unauthenticated users.
|
|
'DEFAULT_PERMISSION_CLASSES': [
|
|
'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
|
|
]
|
|
}
|
|
</code></pre>
|
|
<p>Don't forget to make sure you've also added <code>rest_framework</code> to your <code>INSTALLED_APPS</code>.</p>
|
|
<p>We're ready to create our API now.
|
|
Here's our project's root <code>urls.py</code> module:</p>
|
|
<pre><code>from django.urls import path, include
|
|
from django.contrib.auth.models import User
|
|
from rest_framework import routers, serializers, viewsets
|
|
|
|
# Serializers define the API representation.
|
|
class UserSerializer(serializers.HyperlinkedModelSerializer):
|
|
class Meta:
|
|
model = User
|
|
fields = ['url', 'username', 'email', 'is_staff']
|
|
|
|
# ViewSets define the view behavior.
|
|
class UserViewSet(viewsets.ModelViewSet):
|
|
queryset = User.objects.all()
|
|
serializer_class = UserSerializer
|
|
|
|
# Routers provide an easy way of automatically determining the URL conf.
|
|
router = routers.DefaultRouter()
|
|
router.register(r'users', UserViewSet)
|
|
|
|
# Wire up our API using automatic URL routing.
|
|
# Additionally, we include login URLs for the browsable API.
|
|
urlpatterns = [
|
|
path('', include(router.urls)),
|
|
path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
|
|
]
|
|
</code></pre>
|
|
<p>You can now open the API in your browser at <a href="http://127.0.0.1:8000/">http://127.0.0.1:8000/</a>, and view your new 'users' API. If you use the login control in the top right corner you'll also be able to add, create and delete users from the system.</p>
|
|
<h2 id="quickstart"><a class="toclink" href="#quickstart">Quickstart</a></h2>
|
|
<p>Can't wait to get started? The <a href="tutorial/quickstart/">quickstart guide</a> is the fastest way to get up and running, and building APIs with REST framework.</p>
|
|
<h2 id="development"><a class="toclink" href="#development">Development</a></h2>
|
|
<p>See the <a href="community/contributing/">Contribution guidelines</a> for information on how to clone
|
|
the repository, run the test suite and help maintain the code base of REST
|
|
Framework.</p>
|
|
<h2 id="support"><a class="toclink" href="#support">Support</a></h2>
|
|
<p>For support please see the <a href="https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework">REST framework discussion group</a>, try the <code>#restframework</code> channel on <code>irc.libera.chat</code>, or raise a question on <a href="https://stackoverflow.com/">Stack Overflow</a>, making sure to include the <a href="https://stackoverflow.com/questions/tagged/django-rest-framework">'django-rest-framework'</a> tag.</p>
|
|
<p>For priority support please sign up for a <a href="https://fund.django-rest-framework.org/topics/funding/">professional or premium sponsorship plan</a>.</p>
|
|
<h2 id="security"><a class="toclink" href="#security">Security</a></h2>
|
|
<p><strong>Please report security issues by emailing security@encode.io</strong>.</p>
|
|
<p>The project maintainers will then work with you to resolve any issues where required, prior to any public disclosure.</p>
|
|
<h2 id="license"><a class="toclink" href="#license">License</a></h2>
|
|
<p>Copyright © 2011-present, <a href="https://www.encode.io/">Encode OSS Ltd</a>.
|
|
All rights reserved.</p>
|
|
<p>Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are met:</p>
|
|
<ul>
|
|
<li>
|
|
<p>Redistributions of source code must retain the above copyright notice, this
|
|
list of conditions and the following disclaimer.</p>
|
|
</li>
|
|
<li>
|
|
<p>Redistributions in binary form must reproduce the above copyright notice,
|
|
this list of conditions and the following disclaimer in the documentation
|
|
and/or other materials provided with the distribution.</p>
|
|
</li>
|
|
<li>
|
|
<p>Neither the name of the copyright holder nor the names of its
|
|
contributors may be used to endorse or promote products derived from
|
|
this software without specific prior written permission.</p>
|
|
</li>
|
|
</ul>
|
|
<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
|
|
|
|
|
|
</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> |