django-rest-framework/docs/api-guide/renderers.md

405 lines
18 KiB
Markdown
Raw Normal View History

2012-09-09 01:06:13 +04:00
<a class="github" href="renderers.py"></a>
2012-09-01 23:26:27 +04:00
# Renderers
2012-09-27 00:47:19 +04:00
> Before a TemplateResponse instance can be returned to the client, it must be rendered. The rendering process takes the intermediate representation of template and context, and turns it into the final byte stream that can be served to the client.
>
> &mdash; [Django documentation][cite]
2012-09-01 23:26:27 +04:00
2012-10-21 18:34:07 +04:00
REST framework includes a number of built in Renderer classes, that allow you to return responses with various media types. There is also support for defining your own custom renderers, which gives you the flexibility to design your own media types.
2012-10-02 13:39:28 +04:00
## How the renderer is determined
The set of valid renderers for a view is always defined as a list of classes. When a view is entered REST framework will perform content negotiation on the incoming request, and determine the most appropriate renderer to satisfy the request.
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.
2013-05-28 18:09:23 +04:00
For more information see the documentation on [content negotiation][conneg].
2012-10-02 13:39:28 +04:00
## Setting the renderers
The default set of renderers may be set globally, using the `DEFAULT_RENDERER_CLASSES` setting. For example, the following settings would use `YAML` as the main media type and also include the self describing API.
2012-10-02 13:39:28 +04:00
REST_FRAMEWORK = {
'DEFAULT_RENDERER_CLASSES': (
2012-10-02 13:39:28 +04:00
'rest_framework.renderers.YAMLRenderer',
'rest_framework.renderers.BrowsableAPIRenderer',
2012-10-02 13:39:28 +04:00
)
}
You can also set the renderers used for an individual view, or viewset,
using the `APIView` class based views.
2012-10-02 13:39:28 +04:00
class UserCountView(APIView):
"""
A view that returns the count of active users, in JSON or JSONp.
"""
renderer_classes = (JSONRenderer, JSONPRenderer)
def get(self, request, format=None):
user_count = User.objects.filter(active=True).count()
content = {'user_count': user_count}
return Response(content)
Or, if you're using the `@api_view` decorator with function based views.
2012-10-29 12:32:11 +04:00
@api_view(['GET'])
2012-10-15 01:43:07 +04:00
@renderer_classes((JSONRenderer, JSONPRenderer))
2012-10-02 13:39:28 +04:00
def user_count_view(request, format=None):
"""
A view that returns the count of active users, in JSON or JSONp.
"""
user_count = User.objects.filter(active=True).count()
content = {'user_count': user_count}
return Response(content)
## Ordering of renderer classes
It's important when specifying the renderer classes for your API to think about what priority you want to assign to each media type. If a client underspecifies the representations it can accept, such as sending an `Accept: */*` header, or not including an `Accept` header at all, then REST framework will select the first renderer in the list to use for the response.
For example if your API serves JSON responses and the HTML browsable API, you might want to make `JSONRenderer` your default renderer, in order to send `JSON` responses to clients that do not specify an `Accept` header.
2012-10-02 13:39:28 +04:00
If your API includes views that can serve both regular webpages and API responses depending on the request, then you might consider making `TemplateHTMLRenderer` your default renderer, in order to play nicely with older browsers that send [broken accept headers][browser-accept-headers].
2012-10-05 17:22:02 +04:00
---
2012-10-05 16:51:09 +04:00
# API Reference
2012-09-27 00:47:19 +04:00
## JSONRenderer
2013-05-22 19:46:15 +04:00
Renders the request data into `JSON`, using utf-8 encoding.
2013-05-28 18:09:23 +04:00
Note that non-ascii characters will be rendered using JSON's `\uXXXX` character escape. For example:
2013-05-22 19:46:15 +04:00
{"unicode black star": "\u2605"}
2012-10-02 13:39:28 +04:00
2012-10-15 01:43:07 +04:00
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`.
2013-05-22 19:46:15 +04:00
{
"unicode black star": "\u2605"
}
2012-10-15 01:43:07 +04:00
**.media_type**: `application/json`
**.format**: `'.json'`
2012-10-02 13:39:28 +04:00
2013-05-22 19:46:15 +04:00
**.charset**: `utf-8`
2013-05-21 00:00:56 +04:00
## UnicodeJSONRenderer
2013-05-21 00:00:56 +04:00
Renders the request data into `JSON`, using utf-8 encoding.
2013-05-28 18:09:23 +04:00
Note that non-ascii characters will not be character escaped. For example:
2013-05-22 19:46:15 +04:00
{"unicode black star": "★"}
2013-05-21 00:00:56 +04:00
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`.
2013-05-22 19:46:15 +04:00
{
"unicode black star": "★"
}
Both the `JSONRenderer` and `UnicodeJSONRenderer` styles conform to [RFC 4627][rfc4627], and are syntactically valid JSON.
2013-05-21 00:00:56 +04:00
**.media_type**: `application/json`
**.format**: `'.json'`
**.charset**: `utf-8`
2012-09-27 00:47:19 +04:00
## JSONPRenderer
2012-10-15 01:43:07 +04:00
Renders the request data into `JSONP`. The `JSONP` media type provides a mechanism of allowing cross-domain AJAX requests, by wrapping a `JSON` response in a javascript callback.
The javascript callback function must be set by the client including a `callback` URL query parameter. For example `http://example.com/api/users?callback=jsonpCallback`. If the callback function is not explicitly set by the client it will default to `'callback'`.
2012-10-02 13:39:28 +04:00
2013-01-27 21:23:56 +04:00
**Note**: If you require cross-domain AJAX requests, you may want to consider using the more modern approach of [CORS][cors] as an alternative to `JSONP`. See the [CORS documentation][cors-docs] for more details.
2012-10-15 01:43:07 +04:00
**.media_type**: `application/javascript`
**.format**: `'.jsonp'`
2012-10-02 13:39:28 +04:00
2013-05-22 19:46:15 +04:00
**.charset**: `utf-8`
2013-05-21 00:00:56 +04:00
2012-09-27 00:47:19 +04:00
## YAMLRenderer
2012-10-15 01:43:07 +04:00
Renders the request data into `YAML`.
2013-02-23 00:46:20 +04:00
Requires the `pyyaml` package to be installed.
2012-10-15 01:43:07 +04:00
**.media_type**: `application/yaml`
2012-10-02 13:39:28 +04:00
2012-10-15 01:43:07 +04:00
**.format**: `'.yaml'`
2012-10-02 13:39:28 +04:00
2013-05-21 00:00:56 +04:00
**.charset**: `utf-8`
2012-09-27 00:47:19 +04:00
## XMLRenderer
2012-10-15 01:43:07 +04:00
Renders REST framework's default style of `XML` response content.
2012-10-02 13:39:28 +04:00
2012-10-15 16:27:50 +04:00
Note that the `XML` markup language is used typically used as the base language for more strictly defined domain-specific languages, such as `RSS`, `Atom`, and `XHTML`.
2012-10-15 01:43:07 +04:00
If you are considering using `XML` for your API, you may want to consider implementing a custom renderer and parser for your specific requirements, and using an existing domain-specific media-type, or creating your own custom XML-based media-type.
**.media_type**: `application/xml`
**.format**: `'.xml'`
2012-10-02 13:39:28 +04:00
2013-05-21 00:00:56 +04:00
**.charset**: `utf-8`
## TemplateHTMLRenderer
2012-10-05 16:04:34 +04:00
Renders data to HTML, using Django's standard template rendering.
Unlike other renderers, the data passed to the `Response` does not need to be serialized. Also, unlike other renderers, you may want to include a `template_name` argument when creating the `Response`.
The TemplateHTMLRenderer will create a `RequestContext`, using the `response.data` as the context dict, and determine a template name to use to render the context.
2012-10-05 16:04:34 +04:00
The template name is determined by (in order of preference):
2013-02-22 12:39:50 +04:00
1. An explicit `template_name` argument passed to the response.
2012-10-05 16:04:34 +04:00
2. An explicit `.template_name` attribute set on this class.
3. The return result of calling `view.get_template_names()`.
An example of a view that uses `TemplateHTMLRenderer`:
2012-10-05 16:04:34 +04:00
class UserDetail(generics.RetrieveUserAPIView):
"""
A view that returns a templated HTML representations of a given user.
"""
2013-04-25 01:40:24 +04:00
queryset = User.objects.all()
renderer_classes = (TemplateHTMLRenderer,)
2012-10-09 19:44:49 +04:00
def get(self, request, *args, **kwargs)
self.object = self.get_object()
2012-10-26 19:30:45 +04:00
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.
2012-10-02 13:39:28 +04:00
2012-10-15 01:43:07 +04:00
**.media_type**: `text/html`
2012-10-02 13:39:28 +04:00
2012-10-15 01:43:07 +04:00
**.format**: `'.html'`
2012-09-27 00:47:19 +04:00
2013-05-21 00:00:56 +04:00
**.charset**: `utf-8`
See also: `StaticHTMLRenderer`
## StaticHTMLRenderer
A simple renderer that simply returns pre-rendered HTML. Unlike other renderers, the data passed to the response object should be a string representing the content to be returned.
An example of a view that uses `TemplateHTMLRenderer`:
@api_view(('GET',))
@renderer_classes((StaticHTMLRenderer,))
def simple_html_view(request):
data = '<html><body><h1>Hello, world</h1></body></html>'
return Response(data)
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.
**.media_type**: `text/html`
**.format**: `'.html'`
2013-05-21 00:00:56 +04:00
**.charset**: `utf-8`
See also: `TemplateHTMLRenderer`
## BrowsableAPIRenderer
Renders data into HTML for the Browsable API. This renderer will determine which other renderer would have been given highest priority, and use that to display an API style response within the HTML page.
2012-10-15 01:43:07 +04:00
**.media_type**: `text/html`
2012-10-15 01:43:07 +04:00
**.format**: `'.api'`
2013-05-21 00:00:56 +04:00
**.charset**: `utf-8`
#### Customizing BrowsableAPIRenderer
By default the response content will be rendered with the highest priority renderer apart from `BrowseableAPIRenderer`. If you need to customize this behavior, for example to use HTML as the default return format, but use JSON in the browsable API, you can do so by overriding the `get_default_renderer()` method. For example:
class CustomBrowsableAPIRenderer(BrowsableAPIRenderer):
def get_default_renderer(self, view):
return JSONRenderer()
2013-07-01 16:59:05 +04:00
## MultiPartRenderer
This renderer is used for rendering HTML multipart form data. **It is not suitable as a response renderer**, but is instead used for creating test requests, using REST framework's [test client and test request factory][testing].
**.media_type**: `multipart/form-data; boundary=BoUnDaRyStRiNg`
**.format**: `'.multipart'`
**.charset**: `utf-8`
2012-10-15 01:43:07 +04:00
---
2012-10-15 01:43:07 +04:00
# Custom renderers
2012-09-27 00:47:19 +04:00
To implement a custom renderer, you should override `BaseRenderer`, set the `.media_type` and `.format` properties, and implement the `.render(self, data, media_type=None, renderer_context=None)` method.
2012-10-02 13:39:28 +04:00
2013-08-07 22:00:06 +04:00
The method should return a bytestring, which will be used as the body of the HTTP response.
2013-05-21 00:00:56 +04:00
The arguments passed to the `.render()` method are:
2012-10-15 01:43:07 +04:00
### `data`
The request data, as set by the `Response()` instantiation.
2012-10-15 01:43:07 +04:00
### `media_type=None`
2013-05-28 19:13:12 +04:00
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"`.
2012-10-15 01:43:07 +04:00
### `renderer_context=None`
2013-05-28 19:13:12 +04:00
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`.
2012-10-15 16:27:50 +04:00
## Example
The following is an example plaintext renderer that will return a response with the `data` parameter as the content of the response.
from django.utils.encoding import smart_unicode
from rest_framework import renderers
2013-05-21 00:00:56 +04:00
class PlainTextRenderer(renderers.BaseRenderer):
2012-10-15 16:27:50 +04:00
media_type = 'text/plain'
format = 'txt'
def render(self, data, media_type=None, renderer_context=None):
2013-05-21 00:00:56 +04:00
return data.encode(self.charset)
## Setting the character set
By default renderer classes are assumed to be using the `UTF-8` encoding. To use a different encoding, set the `charset` attribute on the renderer.
class PlainTextRenderer(renderers.BaseRenderer):
media_type = 'text/plain'
format = 'txt'
charset = 'iso-8859-1'
def render(self, data, media_type=None, renderer_context=None):
return data.encode(self.charset)
2013-05-22 19:46:15 +04:00
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.
2013-05-21 00:00:56 +04:00
class JPEGRenderer(renderers.BaseRenderer):
media_type = 'image/jpeg'
format = 'jpg'
charset = None
def render(self, data, media_type=None, renderer_context=None):
return data
2012-10-15 16:27:50 +04:00
2012-10-05 17:22:02 +04:00
---
2012-10-05 16:51:09 +04:00
# Advanced renderer usage
2012-10-02 13:39:28 +04:00
You can do some pretty flexible things using REST framework's renderers. Some examples...
* 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.
2012-10-05 17:22:02 +04:00
## Varying behaviour by media type
2012-10-02 13:39:28 +04:00
In some cases you might want your view to use different serialization styles depending on the accepted media type. If you need to do this you can access `request.accepted_renderer` to determine the negotiated renderer that will be used for the response.
For example:
@api_view(('GET',))
@renderer_classes((TemplateHTMLRenderer, JSONRenderer))
2012-10-02 13:39:28 +04:00
def list_users(request):
"""
A view that can return JSON or HTML representations
of the users in the system.
"""
queryset = Users.objects.filter(active=True)
if request.accepted_renderer.format == 'html':
2012-10-02 13:39:28 +04:00
# TemplateHTMLRenderer takes a context dict,
# and additionally requires a 'template_name'.
# It does not require serialization.
2012-10-02 13:39:28 +04:00
data = {'users': queryset}
2012-10-05 15:13:44 +04:00
return Response(data, template_name='list_users.html')
2012-10-02 13:39:28 +04:00
# JSONRenderer requires serialized data as normal.
serializer = UserSerializer(instance=queryset)
data = serializer.data
2012-10-02 13:39:28 +04:00
return Response(data)
## Underspecifying the media type
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 `*/*`.
2013-05-28 19:13:12 +04:00
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')
2012-10-02 13:39:28 +04:00
## Designing your media types
2012-10-21 18:34:07 +04:00
For the purposes of many Web APIs, simple `JSON` responses with hyperlinked relations may be sufficient. If you want to fully embrace RESTful design and [HATEOAS] you'll need to consider the design and usage of your media types in more detail.
2012-10-02 13:39:28 +04:00
In [the words of Roy Fielding][quote], "A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types.".
For good examples of custom media types, see GitHub's use of a custom [application/vnd.github+json] media type, and Mike Amundsen's IANA approved [application/vnd.collection+json] JSON-based hypermedia.
## HTML error views
Typically a renderer will behave the same regardless of if it's dealing with a regular response, or with a response caused by an exception being raised, such as an `Http404` or `PermissionDenied` exception, or a subclass of `APIException`.
If you're using either the `TemplateHTMLRenderer` or the `StaticHTMLRenderer` and an exception is raised, the behavior is slightly different, and mirrors [Django's default handling of error views][django-error-views].
Exceptions raised and handled by an HTML renderer will attempt to render using one of the following methods, by order of precedence.
* Load and render a template named `{status_code}.html`.
* Load and render a template named `api_exception.html`.
* Render the HTTP status code and text, for example "404 Not Found".
Templates will render with a `RequestContext` which includes the `status_code` and `details` keys.
2013-05-18 17:47:39 +04:00
**Note**: If `DEBUG=True`, Django's standard traceback error page will be displayed instead of rendering the HTTP status code and text.
---
# Third party packages
The following third party packages are also available.
2013-05-21 20:45:25 +04:00
## MessagePack
2013-01-14 21:38:45 +04:00
[MessagePack][messagepack] is a fast, efficient binary serialization format. [Juan Riaza][juanriaza] maintains the [djangorestframework-msgpack][djangorestframework-msgpack] package which provides MessagePack renderer and parser support for REST framework.
2013-05-21 20:45:25 +04:00
## CSV
2013-01-14 21:38:32 +04:00
Comma-separated values are a plain-text tabular data format, that can be easily imported into spreadsheet applications. [Mjumbe Poe][mjumbewu] maintains the [djangorestframework-csv][djangorestframework-csv] package which provides CSV renderer support for REST framework.
2012-10-02 13:39:28 +04:00
[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
2013-05-22 19:46:15 +04:00
[rfc4627]: http://www.ietf.org/rfc/rfc4627.txt
2013-01-27 21:23:56 +04:00
[cors]: http://www.w3.org/TR/cors/
[cors-docs]: ../topics/ajax-csrf-cors.md
2013-07-01 16:59:05 +04:00
[testing]: testing.md
2012-10-02 13:39:28 +04:00
[HATEOAS]: http://timelessrepo.com/haters-gonna-hateoas
[quote]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
[application/vnd.github+json]: http://developer.github.com/v3/media/
[application/vnd.collection+json]: http://www.amundsen.com/media-types/collection/
[django-error-views]: https://docs.djangoproject.com/en/dev/topics/http/views/#customizing-error-views
2013-01-14 21:38:45 +04:00
[messagepack]: http://msgpack.org/
[juanriaza]: https://github.com/juanriaza
2013-01-14 21:38:45 +04:00
[mjumbewu]: https://github.com/mjumbewu
[djangorestframework-msgpack]: https://github.com/juanriaza/django-rest-framework-msgpack
[djangorestframework-csv]: https://github.com/mjumbewu/django-rest-framework-csv