mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-09-22 11:59:04 +03:00
51 lines
1.9 KiB
ReStructuredText
51 lines
1.9 KiB
ReStructuredText
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".
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
reverse(viewname, ..., request=None)
|
|
-------------------------------
|
|
|
|
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
|
|
|
|
class MyView(View):
|
|
def get(self, request):
|
|
context = {
|
|
'url': reverse('year-summary', args=[1945], request=request)
|
|
}
|
|
|
|
return Response(context)
|
|
|
|
reverse_lazy(viewname, ..., request=None)
|
|
------------------------------------
|
|
|
|
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
|