diff options
Diffstat (limited to 'docs/api-guide/renderers.md')
| -rw-r--r-- | docs/api-guide/renderers.md | 37 |
1 files changed, 29 insertions, 8 deletions
diff --git a/docs/api-guide/renderers.md b/docs/api-guide/renderers.md index a5eba9fc..b627c930 100644 --- a/docs/api-guide/renderers.md +++ b/docs/api-guide/renderers.md @@ -14,7 +14,7 @@ The set of valid renderers for a view is always defined as a list of classes. W The basic process of content negotiation involves examining the request's `Accept` header, to determine which media types it expects in the response. Optionally, format suffixes on the URL may be used to explicitly request a particular representation. For example the URL `http://example.com/api/users_count.json` might be an endpoint that always returns JSON data. -For more information see the documentation on [content negotation][conneg]. +For more information see the documentation on [content negotiation][conneg]. ## Setting the renderers @@ -67,22 +67,40 @@ If your API includes views that can serve both regular webpages and API response ## JSONRenderer -Renders the request data into `JSON`, using ASCII encoding. +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: + + {"unicode black star": "\u2605"} 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" + } + **.media_type**: `application/json` **.format**: `'.json'` -**.charset**: `iso-8859-1` +**.charset**: `utf-8` ## 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. + **.media_type**: `application/json` **.format**: `'.json'` @@ -101,7 +119,7 @@ The javascript callback function must be set by the client including a `callback **.format**: `'.jsonp'` -**.charset**: `iso-8859-1` +**.charset**: `utf-8` ## YAMLRenderer @@ -215,13 +233,13 @@ The request data, as set by the `Response()` instantiation. ### `media_type=None` -Optional. If provided, this is the accepted media type, as determined by the content negotiation stage. +Optional. If provided, this is the accepted media type, as determined by the content negotiation stage. Depending on the client's `Accept:` header, this may be more specific than the renderer's `media_type` attribute, and may include media type parameters. For example `"application/json; nested=true"`. ### `renderer_context=None` -Optional. If provided, this is a dictionary of contextual information provided by the view. +Optional. If provided, this is a dictionary of contextual information provided by the view. By default this will include the following keys: `view`, `request`, `response`, `args`, `kwargs`. @@ -252,7 +270,9 @@ By default renderer classes are assumed to be using the `UTF-8` encoding. To us def render(self, data, media_type=None, renderer_context=None): return data.encode(self.charset) -If the renderer returns a raw bytestring, you should set a charset value of `None`, which will ensure the `Content-Type` header of the response will not have a `charset` value set. Doing so will also ensure that the browsable API will not attempt to display the binary content as a string. +Note that if a renderer class returns a unicode string, then the response content will be coerced into a bytestring by the `Response` class, with the `charset` attribute set on the renderer used to determine the encoding. + +If the renderer returns a bytestring representing raw binary content, you should set a charset value of `None`, which will ensure the `Content-Type` header of the response will not have a `charset` value set. Doing so will also ensure that the browsable API will not attempt to display the binary content as a string. class JPEGRenderer(renderers.BaseRenderer): media_type = 'image/jpeg' @@ -305,7 +325,7 @@ For example: In some cases you might want a renderer to serve a range of media types. In this case you can underspecify the media types it should respond to, by using a `media_type` value such as `image/*`, or `*/*`. -If you underspecify the renderer's media type, you should make sure to specify the media type explictly when you return the response, using the `content_type` attribute. For example: +If you underspecify the renderer's media type, you should make sure to specify the media type explicitly when you return the response, using the `content_type` attribute. For example: return Response(data, content_type='image/png') @@ -350,6 +370,7 @@ Comma-separated values are a plain-text tabular data format, that can be easily [cite]: https://docs.djangoproject.com/en/dev/ref/template-response/#the-rendering-process [conneg]: content-negotiation.md [browser-accept-headers]: http://www.gethifi.com/blog/browser-rest-http-accept-headers +[rfc4627]: http://www.ietf.org/rfc/rfc4627.txt [cors]: http://www.w3.org/TR/cors/ [cors-docs]: ../topics/ajax-csrf-cors.md [HATEOAS]: http://timelessrepo.com/haters-gonna-hateoas |