diff options
Diffstat (limited to 'docs/howto/reverse.rst')
| -rw-r--r-- | docs/howto/reverse.rst | 31 |
1 files changed, 21 insertions, 10 deletions
diff --git a/docs/howto/reverse.rst b/docs/howto/reverse.rst index 73b8fa4d..0a7af0e9 100644 --- a/docs/howto/reverse.rst +++ b/docs/howto/reverse.rst @@ -1,23 +1,32 @@ Returning URIs from your Web APIs ================================= -As a rule, it's probably better practice to return absolute URIs from you web APIs, e.g. "http://example.com/foobar", rather than returning relative URIs, e.g. "/foobar". +As a rule, it's probably better practice to return absolute URIs from you web +APIs, e.g. "http://example.com/foobar", rather than returning relative URIs, +e.g. "/foobar". The advantages of doing so are: * It's more explicit. * It leaves less work for your API clients. -* 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. -* It allows us to easily do things like markup HTML representations with hyperlinks. +* 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. +* It allows us to easily do things like markup HTML representations + with hyperlinks. -Django REST framework provides two utility functions to make it simpler to return absolute URIs from your Web API. +Django REST framework provides two utility functions to make it simpler to +return absolute URIs from your Web API. -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. +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. -reverse(viewname, request, ...) +reverse(viewname, ..., request=None) ------------------------------- -The :py:func:`~reverse.reverse` function has the same behavior as `django.core.urlresolvers.reverse`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port:: +The `reverse` function has the same behavior as +`django.core.urlresolvers.reverse`_, except that it optionally takes a request +keyword argument, which it uses to return a fully qualified URL. from djangorestframework.reverse import reverse from djangorestframework.views import View @@ -25,15 +34,17 @@ The :py:func:`~reverse.reverse` function has the same behavior as `django.core.u class MyView(View): def get(self, request): context = { - 'url': reverse('year-summary', request, args=[1945]) + 'url': reverse('year-summary', args=[1945], request=request) } return Response(context) -reverse_lazy(viewname, request, ...) +reverse_lazy(viewname, ..., request=None) ------------------------------------ -The :py:func:`~reverse.reverse_lazy` function has the same behavior as `django.core.urlresolvers.reverse_lazy`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port. +The `reverse_lazy` function has the same behavior as +`django.core.urlresolvers.reverse_lazy`_, except that it optionally takes a +request keyword argument, which it uses to return a fully qualified URL. .. _django.core.urlresolvers.reverse: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse .. _django.core.urlresolvers.reverse_lazy: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy |