From 40d1821f2d81f822fff9b85691073ab069edb847 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 5 Sep 2012 10:01:43 +0100 Subject: Add missing doc files --- docs/api-guide/authentication.md | 9 +++++++++ docs/api-guide/permissions.md | 1 + docs/api-guide/reverse.md | 41 ++++++++++++++++++++++++++++++++++++++++ docs/api-guide/settings.md | 31 ++++++++++++++++++++++++++++++ docs/api-guide/throttling.md | 1 + docs/api-guide/urls.md | 41 ---------------------------------------- docs/index.md | 8 ++++++-- docs/template.html | 3 ++- 8 files changed, 91 insertions(+), 44 deletions(-) create mode 100644 docs/api-guide/authentication.md create mode 100644 docs/api-guide/permissions.md create mode 100644 docs/api-guide/reverse.md create mode 100644 docs/api-guide/settings.md create mode 100644 docs/api-guide/throttling.md delete mode 100644 docs/api-guide/urls.md (limited to 'docs') diff --git a/docs/api-guide/authentication.md b/docs/api-guide/authentication.md new file mode 100644 index 00000000..76aaba8a --- /dev/null +++ b/docs/api-guide/authentication.md @@ -0,0 +1,9 @@ +# Authentication + +REST framework provides a number of authentication policies out of the box, and also allows you to implement custom policies. + +## BasicAuthentication + +## TokenBasicAuthentication + +## SessionAuthentication diff --git a/docs/api-guide/permissions.md b/docs/api-guide/permissions.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/api-guide/permissions.md @@ -0,0 +1 @@ + diff --git a/docs/api-guide/reverse.md b/docs/api-guide/reverse.md new file mode 100644 index 00000000..c39ff8f6 --- /dev/null +++ b/docs/api-guide/reverse.md @@ -0,0 +1,41 @@ +# Returning URIs from your Web APIs + +> The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components. +> +> — Roy Fielding, [Architectural Styles and the Design of Network-based Software Architectures][cite] + +As a rule, it's probably better practice to return absolute URIs from you web APIs, such as `http://example.com/foobar`, rather than returning relative URIs, such as `/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 use to easily do things like markup HTML representations with hyperlinks. + +REST framework provides two utility functions to make it more simple 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 it's output for you, which makes browsing the API much easier. + +## reverse(viewname, request, *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. + + from djangorestframework.utils import reverse + from djangorestframework.views import APIView + + class MyView(APIView): + def get(self, request): + content = { + ... + 'url': reverse('year-summary', request, args=[1945]) + } + return Response(content) + +## reverse_lazy(viewname, request, *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. + +[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 \ No newline at end of file diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md new file mode 100644 index 00000000..c7bae30d --- /dev/null +++ b/docs/api-guide/settings.md @@ -0,0 +1,31 @@ +# Settings + +Settings for REST framework are all namespaced in the `API_SETTINGS` setting. +For example your project's `settings.py` file might look like this: + + API_SETTINGS = { + 'DEFAULT_RENDERERS': ( + 'djangorestframework.renderers.JSONRenderer', + 'djangorestframework.renderers.YAMLRenderer', + ) + 'DEFAULT_PARSERS': ( + 'djangorestframework.parsers.JSONParser', + 'djangorestframework.parsers.YAMLParser', + ) + } + +## DEFAULT_RENDERERS + +A list or tuple of renderer classes. + +Default: + + ( + 'djangorestframework.renderers.JSONRenderer', + 'djangorestframework.renderers.DocumentingHTMLRenderer')` + +## DEFAULT_PARSERS + +A list or tuple of parser classes. + +Default: `()` diff --git a/docs/api-guide/throttling.md b/docs/api-guide/throttling.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/docs/api-guide/throttling.md @@ -0,0 +1 @@ + diff --git a/docs/api-guide/urls.md b/docs/api-guide/urls.md deleted file mode 100644 index c39ff8f6..00000000 --- a/docs/api-guide/urls.md +++ /dev/null @@ -1,41 +0,0 @@ -# Returning URIs from your Web APIs - -> The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components. -> -> — Roy Fielding, [Architectural Styles and the Design of Network-based Software Architectures][cite] - -As a rule, it's probably better practice to return absolute URIs from you web APIs, such as `http://example.com/foobar`, rather than returning relative URIs, such as `/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 use to easily do things like markup HTML representations with hyperlinks. - -REST framework provides two utility functions to make it more simple 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 it's output for you, which makes browsing the API much easier. - -## reverse(viewname, request, *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. - - from djangorestframework.utils import reverse - from djangorestframework.views import APIView - - class MyView(APIView): - def get(self, request): - content = { - ... - 'url': reverse('year-summary', request, args=[1945]) - } - return Response(content) - -## reverse_lazy(viewname, request, *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. - -[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 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 25cab398..6b7574b1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -79,9 +79,11 @@ The API guide is your complete reference manual to all the functionality provide * [Serializers][serializers] * [Authentication][authentication] * [Permissions][permissions] +* [Throttling][throttling] * [Exceptions][exceptions] * [Status codes][status] -* [Returning URLs][urls] +* [Returning URLs][reverse] +* [Settings][settings] ## Topics @@ -147,9 +149,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. [serializers]: api-guide/serializers.md [authentication]: api-guide/authentication.md [permissions]: api-guide/permissions.md +[throttling]: api-guide/throttling.md [exceptions]: api-guide/exceptions.md [status]: api-guide/status.md -[urls]: api-guide/urls.md +[reverse]: api-guide/reverse.md +[settings]: api-guide/settings.md [csrf]: topics/csrf.md [formoverloading]: topics/formoverloading.md diff --git a/docs/template.html b/docs/template.html index e452ead7..2c3572e1 100644 --- a/docs/template.html +++ b/docs/template.html @@ -94,7 +94,8 @@ margin-top: 5px;
  • Throttling
  • Exceptions
  • Status codes
    • -
  • Returning URLs
    • +
  • Returning URLs
    • +
  • Settings
  • -- cgit v1.2.3