From 52a2ff8f77dc22a65e6f5780de8183f261472342 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Tue, 9 Oct 2012 16:44:49 +0100 Subject: [PATCH] Docs tweaks --- docs/api-guide/renderers.md | 2 +- docs/api-guide/reverse.md | 12 +++++++++--- docs/topics/rest-hypermedia-hateoas.md | 8 ++++---- 3 files changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index 5d93ea388..1b266f7ef 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -110,7 +110,7 @@ An example of a view that uses `HTMLRenderer`: model = Users renderer_classes = (HTMLRenderer,) - def get(self, request, \*args, **kwargs) + def get(self, request, *args, **kwargs) self.object = self.get_object() return Response(self.object, template_name='user_detail.html') diff --git a/docs/api-guide/reverse.md b/docs/api-guide/reverse.md index 8485087e4..82cadffc3 100644 --- a/docs/api-guide/reverse.md +++ b/docs/api-guide/reverse.md @@ -21,10 +21,12 @@ There's no requirement for you to use them, but if you do then the self-describi ## reverse -**Signature:** `reverse(viewname, request, *args, **kwargs)` +**Signature:** `reverse(viewname, *args, **kwargs)` Has the same behavior as [`django.core.urlresolvers.reverse`][reverse], except that it returns a fully qualified URL, using the request to determine the host and port. +You should **include the request as a keyword argument** to the function, for example: + import datetime from rest_framework.utils import reverse from rest_framework.views import APIView @@ -34,16 +36,20 @@ Has the same behavior as [`django.core.urlresolvers.reverse`][reverse], except t year = datetime.datetime.now().year data = { ... - 'year-summary-url': reverse('year-summary', request, args=[year]) + 'year-summary-url': reverse('year-summary', args=[year], request=request) } return Response(data) ## reverse_lazy -**Signature:** `reverse_lazy(viewname, request, *args, **kwargs)` +**Signature:** `reverse_lazy(viewname, *args, **kwargs)` Has the same behavior as [`django.core.urlresolvers.reverse_lazy`][reverse-lazy], except that it returns a fully qualified URL, using the request to determine the host and port. +As with the `reverse` function, you should **include the request as a keyword argument** to the function, for example: + + api_root = reverse_lazy('api-root', request=request) + [cite]: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm#sec_5_1_5 [reverse]: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse [reverse-lazy]: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy diff --git a/docs/topics/rest-hypermedia-hateoas.md b/docs/topics/rest-hypermedia-hateoas.md index 0e183a492..b58dfcb70 100644 --- a/docs/topics/rest-hypermedia-hateoas.md +++ b/docs/topics/rest-hypermedia-hateoas.md @@ -4,15 +4,15 @@ > > — Mike Amundsen, [REST fest 2012 keynote][cite]. -First off, the disclaimer. The name "Django REST framework" was choosen with a view to making 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". +First off, the disclaimer. The name "Django REST framework" was choosen 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". If you are serious about designing a Hypermedia APIs, you should look to resources outside of this documentation to help inform your design choices. The following fall into the "required reading" category. -* Fielding's dissertation - [Architectural Styles and +* Roy Fielding's dissertation - [Architectural Styles and the Design of Network-based Software Architectures][dissertation]. -* Fielding's "[REST APIs must be hypertext-driven][hypertext-driven]" blog post. +* Roy Fielding's "[REST APIs must be hypertext-driven][hypertext-driven]" blog post. * Leonard Richardson & Sam Ruby's [RESTful Web Services][restful-web-services]. * Mike Amundsen's [Building Hypermedia APIs with HTML5 and Node][building-hypermedia-apis]. * Steve Klabnik's [Designing Hypermedia APIs][designing-hypermedia-apis]. @@ -32,7 +32,7 @@ REST framework also includes [serialization] and [parser]/[renderer] components ### What REST framework *doesn't* provide. -What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create HATEOAS style APIs. Doing so would involve making opinionated choices about API design that should really remain outside of the framework's scope. +What REST framework doesn't do is give you is machine readable hypermedia formats such as [Collection+JSON][collection] or HTML [microformats] by default, or the ability to auto-magically create fully HATEOAS style APIs that include 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. [cite]: http://vimeo.com/channels/restfest/page:2 [dissertation]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm