mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-11-29 13:04:03 +03:00
515 lines
21 KiB
HTML
515 lines
21 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
<meta charset="utf-8">
|
|
<title>REST, Hypermedia & HATEOAS - 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/rest-hypermedia-hateoas/" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="description" content="Django, API, REST, REST, Hypermedia & HATEOAS">
|
|
<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="../../community/tutorials-and-resources/">
|
|
Next <i class="icon-arrow-right icon-white"></i>
|
|
</a>
|
|
<a class="repo-link btn btn-inverse btn-small " rel="prev" href="../browsable-api/">
|
|
<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="../api-clients/">API Clients</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 >
|
|
<a href="../browsable-api/">The Browsable API</a>
|
|
</li>
|
|
|
|
<li class="active" >
|
|
<a href="./">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.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="#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>
|
|
|
|
|
|
|
|
<div class="promo">
|
|
<hr/>
|
|
<div id="sidebarInclude">
|
|
</div>
|
|
</ul>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="main-content" class="span9">
|
|
|
|
|
|
|
|
<h1 id="rest-hypermedia-hateoas"><a class="toclink" href="#rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></h1>
|
|
<blockquote>
|
|
<p>You keep using that word "REST". I do not think it means what you think it means.</p>
|
|
<p>— Mike Amundsen, <a href="https://vimeo.com/channels/restfest/49503453">REST fest 2012 keynote</a>.</p>
|
|
</blockquote>
|
|
<p>First off, the disclaimer. The name "Django REST framework" was decided back in early 2011 and was chosen simply to sure the project would be easily found by developers. Throughout the documentation we try to use the more simple and technically correct terminology of "Web APIs".</p>
|
|
<p>If you are serious about designing a Hypermedia API, you should look to resources outside of this documentation to help inform your design choices.</p>
|
|
<p>The following fall into the "required reading" category.</p>
|
|
<ul>
|
|
<li>Roy Fielding's dissertation - <a href="https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">Architectural Styles and
|
|
the Design of Network-based Software Architectures</a>.</li>
|
|
<li>Roy Fielding's "<a href="https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven">REST APIs must be hypertext-driven</a>" blog post.</li>
|
|
<li>Leonard Richardson & Mike Amundsen's <a href="http://restfulwebapis.org/">RESTful Web APIs</a>.</li>
|
|
<li>Mike Amundsen's <a href="https://www.amazon.com/Building-Hypermedia-APIs-HTML5-Node/dp/1449306578">Building Hypermedia APIs with HTML5 and Node</a>.</li>
|
|
<li>Steve Klabnik's <a href="http://designinghypermediaapis.com/">Designing Hypermedia APIs</a>.</li>
|
|
<li>The <a href="https://martinfowler.com/articles/richardsonMaturityModel.html">Richardson Maturity Model</a>.</li>
|
|
</ul>
|
|
<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"><a class="toclink" href="#building-hypermedia-apis-with-rest-framework">Building Hypermedia APIs with REST framework</a></h2>
|
|
<p>REST framework is an agnostic 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>
|
|
<h2 id="what-rest-framework-provides"><a class="toclink" href="#what-rest-framework-provides">What REST framework provides.</a></h2>
|
|
<p>It is self evident that REST framework makes it possible to build Hypermedia APIs. The browsable 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>
|
|
<h2 id="what-rest-framework-doesnt-provide"><a class="toclink" href="#what-rest-framework-doesnt-provide">What REST framework doesn't provide.</a></h2>
|
|
<p>What REST framework doesn't do is give you machine readable hypermedia formats such as <a href="http://stateless.co/hal_specification.html">HAL</a>, <a href="http://www.amundsen.com/media-types/collection/">Collection+JSON</a>, <a href="http://jsonapi.org/">JSON API</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-->
|
|
</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> |