diff options
| author | Xavier Ordoquy | 2014-11-26 16:36:56 +0100 |
|---|---|---|
| committer | Xavier Ordoquy | 2014-11-26 16:36:56 +0100 |
| commit | f5e5ed0077cc477a7b8af98c7b10d8d3701f1a65 (patch) | |
| tree | 252729a9e61deb0dbc1a098feb1c55eae56ca948 /docs/api-guide/renderers.md | |
| parent | 311d315a739f4d1d02e87a09de0bbf9e7b0cee46 (diff) | |
| parent | 2647e1aaaadfc2cfd947c633399dca1060c17401 (diff) | |
| download | django-rest-framework-f5e5ed0077cc477a7b8af98c7b10d8d3701f1a65.tar.bz2 | |
Merge remote-tracking branch 'reference/master' into bugfix/1850
Diffstat (limited to 'docs/api-guide/renderers.md')
| -rw-r--r-- | docs/api-guide/renderers.md | 43 |
1 files changed, 12 insertions, 31 deletions
diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index 20eed70d..035ec1d2 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -1,4 +1,4 @@ -<a class="github" href="renderers.py"></a> +source: renderers.py # Renderers @@ -74,37 +74,18 @@ If your API includes views that can serve both regular webpages and API response Renders the request data into `JSON`, using utf-8 encoding. -Note that non-ascii characters will be rendered using JSON's `\uXXXX` character escape. For example: +Note that the default style is to include unicode characters, and render the response using a compact style with no unnecessary whitespace: - {"unicode black star": "\u2605"} + {"unicode black star":"★","value":999} The client may additionally include an `'indent'` media type parameter, in which case the returned `JSON` will be indented. For example `Accept: application/json; indent=4`. { - "unicode black star": "\u2605" + "unicode black star": "★", + "value": 999 } -**.media_type**: `application/json` - -**.format**: `'.json'` - -**.charset**: `None` - -## UnicodeJSONRenderer - -Renders the request data into `JSON`, using utf-8 encoding. - -Note that non-ascii characters will not be character escaped. For example: - - {"unicode black star": "★"} - -The client may additionally include an `'indent'` media type parameter, in which case the returned `JSON` will be indented. For example `Accept: application/json; indent=4`. - - { - "unicode black star": "★" - } - -Both the `JSONRenderer` and `UnicodeJSONRenderer` styles conform to [RFC 4627][rfc4627], and are syntactically valid JSON. +The default JSON encoding style can be altered using the `UNICODE_JSON` and `COMPACT_JSON` settings keys. **.media_type**: `application/json` @@ -134,7 +115,7 @@ The `jsonp` approach is essentially a browser hack, and is [only appropriate for ## YAMLRenderer -Renders the request data into `YAML`. +Renders the request data into `YAML`. Requires the `pyyaml` package to be installed. @@ -150,7 +131,7 @@ Note that non-ascii characters will be rendered using `\uXXXX` character escape. ## UnicodeYAMLRenderer -Renders the request data into `YAML`. +Renders the request data into `YAML`. Requires the `pyyaml` package to be installed. @@ -203,7 +184,7 @@ An example of a view that uses `TemplateHTMLRenderer`: def get(self, request, *args, **kwargs): self.object = self.get_object() return Response({'user': self.object}, template_name='user_detail.html') - + You can use `TemplateHTMLRenderer` either to return regular HTML pages using REST framework, or to return both HTML and API responses from a single endpoint. If you're building websites that use `TemplateHTMLRenderer` along with other renderer classes, you should consider listing `TemplateHTMLRenderer` as the first class in the `renderer_classes` list, so that it will be prioritised first even for browsers that send poorly formed `ACCEPT:` headers. @@ -224,7 +205,7 @@ An example of a view that uses `TemplateHTMLRenderer`: @api_view(('GET',)) @renderer_classes((StaticHTMLRenderer,)) - def simple_html_view(request): + def simple_html_view(request): data = '<html><body><h1>Hello, world</h1></body></html>' return Response(data) @@ -319,7 +300,7 @@ The following is an example plaintext renderer that will return a response with class PlainTextRenderer(renderers.BaseRenderer): media_type = 'text/plain' format = 'txt' - + def render(self, data, media_type=None, renderer_context=None): return data.encode(self.charset) @@ -359,7 +340,7 @@ You can do some pretty flexible things using REST framework's renderers. Some e * Provide either flat or nested representations from the same endpoint, depending on the requested media type. * Serve both regular HTML webpages, and JSON based API responses from the same endpoints. * Specify multiple types of HTML representation for API clients to use. -* Underspecify a renderer's media type, such as using `media_type = 'image/*'`, and use the `Accept` header to vary the encoding of the response. +* Underspecify a renderer's media type, such as using `media_type = 'image/*'`, and use the `Accept` header to vary the encoding of the response. ## Varying behaviour by media type |