2013-11-17 22:26:41 +04:00
<!DOCTYPE html>
< html lang = "en" >
< head > < meta http-equiv = "Content-Type" content = "text/html; charset=UTF-8" >
< meta charset = "utf-8" >
2013-12-23 16:37:56 +04:00
< title > Returning URLs - Django REST framework< / title >
2013-11-17 22:26:41 +04:00
< link href = "http://django-rest-framework.org/img/favicon.ico" rel = "icon" type = "image/x-icon" >
2013-11-18 19:50:29 +04:00
< link rel = "canonical" href = "http://django-rest-framework.org/api-guide/reverse" / >
2013-11-17 22:26:41 +04:00
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< meta name = "description" content = "Django, API, REST, Returning URLs" >
< meta name = "author" content = "Tom Christie" >
<!-- Le styles -->
< link href = "http://django-rest-framework.org/css/prettify.css" rel = "stylesheet" >
< link href = "http://django-rest-framework.org/css/bootstrap.css" rel = "stylesheet" >
< link href = "http://django-rest-framework.org/css/bootstrap-responsive.css" rel = "stylesheet" >
< link href = "http://django-rest-framework.org/css/default.css" rel = "stylesheet" >
<!-- Le HTML5 shim, for IE6 - 8 support of HTML5 elements -->
<!-- [if lt IE 9]>
< script src = "http://html5shim.googlecode.com/svn/trunk/html5.js" > < / script >
<![endif]-->
< 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 >
< / head >
< body onload = "prettyPrint()" class = "reverse-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/tomchristie/django-rest-framework/tree/master" > GitHub< / a >
2013-11-18 19:50:29 +04:00
< a class = "repo-link btn btn-inverse btn-small " href = "../api-guide/exceptions" > Next < i class = "icon-arrow-right icon-white" > < / i > < / a >
< a class = "repo-link btn btn-inverse btn-small " href = "../api-guide/format-suffixes" > < i class = "icon-arrow-left icon-white" > < / i > Previous< / a >
2013-11-17 22:26:41 +04:00
< a class = "repo-link btn btn-inverse btn-small" href = "#searchModal" data-toggle = "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 = "http://django-rest-framework.org" > Django REST framework< / a >
< div class = "nav-collapse collapse" >
< ul class = "nav" >
< li > < a href = "http://django-rest-framework.org" > Home< / a > < / li >
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > Tutorial < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
2013-11-18 19:50:29 +04:00
< li > < a href = "http://django-rest-framework.org/tutorial/quickstart" > Quickstart< / a > < / li >
< li > < a href = "http://django-rest-framework.org/tutorial/1-serialization" > 1 - Serialization< / a > < / li >
< li > < a href = "http://django-rest-framework.org/tutorial/2-requests-and-responses" > 2 - Requests and responses< / a > < / li >
< li > < a href = "http://django-rest-framework.org/tutorial/3-class-based-views" > 3 - Class based views< / a > < / li >
< li > < a href = "http://django-rest-framework.org/tutorial/4-authentication-and-permissions" > 4 - Authentication and permissions< / a > < / li >
< li > < a href = "http://django-rest-framework.org/tutorial/5-relationships-and-hyperlinked-apis" > 5 - Relationships and hyperlinked APIs< / a > < / li >
< li > < a href = "http://django-rest-framework.org/tutorial/6-viewsets-and-routers" > 6 - Viewsets and routers< / a > < / li >
2013-11-17 22:26:41 +04:00
< / ul >
< / li >
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > API Guide < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
2013-11-18 19:50:29 +04:00
< li > < a href = "http://django-rest-framework.org/api-guide/requests" > Requests< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/responses" > Responses< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/views" > Views< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/generic-views" > Generic views< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/viewsets" > Viewsets< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/routers" > Routers< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/parsers" > Parsers< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/renderers" > Renderers< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/serializers" > Serializers< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/fields" > Serializer fields< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/relations" > Serializer relations< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/authentication" > Authentication< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/permissions" > Permissions< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/throttling" > Throttling< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/filtering" > Filtering< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/pagination" > Pagination< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/content-negotiation" > Content negotiation< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/format-suffixes" > Format suffixes< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/reverse" > Returning URLs< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/exceptions" > Exceptions< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/status-codes" > Status codes< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/testing" > Testing< / a > < / li >
< li > < a href = "http://django-rest-framework.org/api-guide/settings" > Settings< / a > < / li >
2013-11-17 22:26:41 +04:00
< / ul >
< / li >
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > Topics < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
2013-11-18 19:50:29 +04:00
< li > < a href = "http://django-rest-framework.org/topics/documenting-your-api" > Documenting your API< / a > < / li >
< li > < a href = "http://django-rest-framework.org/topics/ajax-csrf-cors" > AJAX, CSRF & CORS< / a > < / li >
< li > < a href = "http://django-rest-framework.org/topics/browser-enhancements" > Browser enhancements< / a > < / li >
< li > < a href = "http://django-rest-framework.org/topics/browsable-api" > The Browsable API< / a > < / li >
< li > < a href = "http://django-rest-framework.org/topics/rest-hypermedia-hateoas" > REST, Hypermedia & HATEOAS< / a > < / li >
2013-12-04 19:00:19 +04:00
< li > < a href = "http://django-rest-framework.org/topics/contributing" > Contributing to REST framework< / a > < / li >
2013-11-18 19:50:29 +04:00
< li > < a href = "http://django-rest-framework.org/topics/rest-framework-2-announcement" > 2.0 Announcement< / a > < / li >
< li > < a href = "http://django-rest-framework.org/topics/2.2-announcement" > 2.2 Announcement< / a > < / li >
< li > < a href = "http://django-rest-framework.org/topics/2.3-announcement" > 2.3 Announcement< / a > < / li >
< li > < a href = "http://django-rest-framework.org/topics/release-notes" > Release Notes< / a > < / li >
< li > < a href = "http://django-rest-framework.org/topics/credits" > Credits< / a > < / li >
2013-11-17 22:26:41 +04:00
< / ul >
< / li >
< / ul >
< ul class = "nav pull-right" >
<!-- TODO
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > Version: 2.0.0 < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
< li > < a href = "#" > Trunk< / a > < / li >
< li > < a href = "#" > 2.0.0< / a > < / li >
< / ul >
< / li >
-->
< / ul >
< / div > <!-- /.nav - collapse -->
< / div >
< / div >
< / div >
< div class = "body-content" >
< div class = "container-fluid" >
<!-- Search Modal -->
< div id = "searchModal" 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" >
<!-- Custom google search -->
< script >
(function() {
var cx = '015016005043623903336:rxraeohqk6w';
var gcse = document.createElement('script');
gcse.type = 'text/javascript';
gcse.async = true;
gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
'//www.google.com/cse/cse.js?cx=' + cx;
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(gcse, s);
})();
< / script >
< gcse:search > < / gcse:search >
< / 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" >
<!-- TODO
< p style = "margin-top: -12px" >
< a class = "btn btn-mini btn-primary" style = "width: 60px" > « previous< / a >
< a class = "btn btn-mini btn-primary" style = "float: right; margin-right: 8px; width: 60px;" > next » < / a >
< / p >
-->
< div id = "table-of-contents" >
< ul class = "nav nav-list side-nav well sidebar-nav-fixed" >
< li class = "main" > < a href = "#returning-urls" > Returning URLs< / a > < / li >
< li > < a href = "#reverse" > reverse< / a > < / li >
< li > < a href = "#reverse_lazy" > reverse_lazy< / a > < / li >
< div >
< hr >
2013-12-09 12:47:06 +04:00
< p > < strong > The team behind REST framework is launching a new API service.< / strong > < / p >
2013-11-17 22:26:41 +04:00
< p > If you want to be first in line when we start issuing invitations, please sign up here:< / p >
<!-- Begin MailChimp Signup Form -->
< link href = "//cdn-images.mailchimp.com/embedcode/slim-081711.css" rel = "stylesheet" type = "text/css" >
< style type = "text/css" >
#mc_embed_signup{background:#fff; clear:left; font:14px Helvetica,Arial,sans-serif; }
/* Add your own MailChimp form style overrides in your site stylesheet or in this style block.
We recommend moving this block and the preceding CSS link to the HEAD of your HTML file. */
< / style >
< div id = "mc_embed_signup" style = "background: rgb(245, 245, 245)" >
< form action = "http://dabapps.us1.list-manage1.com/subscribe/post?u=cf73a9994eb5b8d8d461b5dfb&id=cb6af8e8bd" method = "post" id = "mc-embedded-subscribe-form" name = "mc-embedded-subscribe-form" class = "validate" target = "_blank" novalidate >
<!-- <label for="mce - EMAIL">Keep me posted!</label>
--> < input style = "width: 90%" type = "email" value = "" name = "EMAIL" class = "email" id = "mce-EMAIL" placeholder = "email address" required >
< div class = "clear" > < input class = "btn btn-success" type = "submit" value = "Yes, keep me posted!" name = "subscribe" id = "mc-embedded-subscribe" class = "button" > < / div >
< / form >
< / div >
< / style > < / div >
< / ul >
<!-- End mc_embed_signup -->
< / div >
< / div >
< div id = "main-content" class = "span9" >
< p > < a class = "github" href = "https://github.com/tomchristie/django-rest-framework/tree/master/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 >
< p > — Roy Fielding, < a href = "http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5" > Architectural Styles and the Design of Network-based Software Architectures< / a > < / p >
< / blockquote >
< p > As a rule, it's probably better practice to return absolute URIs from your Web APIs, such as < code > http://example.com/foobar< / code > , rather than returning relative URIs, such as < code > /foobar< / code > .< / p >
< p > The advantages of doing so are:< / p >
< ul >
< li > It's more explicit.< / li >
< li > It leaves less work for your API clients.< / li >
< li > There's no ambiguity about the meaning of the string when it's found in representations such as JSON that do not have a native URI type.< / li >
< li > It makes it easy to do things like markup HTML representations with hyperlinks.< / li >
< / ul >
< p > REST framework provides two utility functions to make it more simple to return absolute URIs from your Web API.< / p >
< 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 its output for you, which makes browsing the API much easier.< / p >
< h2 id = "reverse" > reverse< / h2 >
< p > < strong > Signature:< / strong > < code > reverse(viewname, *args, **kwargs)< / code > < / p >
< 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 >
< p > You should < strong > include the request as a keyword argument< / strong > to the function, for example:< / p >
< pre class = "prettyprint lang-py" > < code > from rest_framework.reverse import reverse
from rest_framework.views import APIView
from django.utils.timezone import now
class APIRootView(APIView):
def get(self, request):
year = now().year
data = {
...
'year-summary-url': reverse('year-summary', args=[year], request=request)
}
return Response(data)
< / code > < / pre >
< h2 id = "reverse_lazy" > reverse_lazy< / h2 >
< p > < strong > Signature:< / strong > < code > reverse_lazy(viewname, *args, **kwargs)< / code > < / p >
< p > Has the same behavior as < a href = "https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy" > < code > django.core.urlresolvers.reverse_lazy< / code > < / a > , except that it returns a fully qualified URL, using the request to determine the host and port.< / p >
< p > As with the < code > reverse< / code > function, you should < strong > include the request as a keyword argument< / strong > to the function, for example:< / p >
< pre class = "prettyprint lang-py" > < code > api_root = reverse_lazy('api-root', request=request)
< / code > < / pre >
< / div > <!-- /span -->
< / div > <!-- /row -->
< / div > <!-- /.fluid - container -->
< / div > <!-- /.body content -->
< div id = "push" > < / div >
< / div > <!-- /.wrapper -->
< footer class = "span12" >
< p > Sponsored by < a href = "http://dabapps.com/" > DabApps< / a > .< / a > < / p >
< / footer >
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
< script src = "http://django-rest-framework.org/js/jquery-1.8.1-min.js" > < / script >
< script src = "http://django-rest-framework.org/js/prettify-1.0.js" > < / script >
< script src = "http://django-rest-framework.org/js/bootstrap-2.1.1-min.js" > < / script >
< script >
//$('.side-nav').scrollspy()
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 to no higher than browser window
$('.side-nav').css('max-height', window.innerHeight - 130);
$(function(){
$(window).resize(function(){
$('.side-nav').css('max-height', window.innerHeight - 130);
});
});
< / script >
< / body > < / html >
