Machine interacting web services tend to use morestructured formats for sending data than form-encoded, since they'resending more complex data than simple forms
— Malcom Tredinnick,Django developers group
REST framework includes a number of built-in Parser classes, that allow you to accept requests with various media types. There is also support for defining your own custom parsers, which gives you the flexibility to design the media types that your API accepts.
The set of valid parsers for a view is always defined as a list of classes. Whenrequest.data is accessed, REST framework will examine theContent-Type header on the incoming request, and determine which parser to use to parse the request content.
Note
When developing client applications always remember to make sure you're setting theContent-Type header when sending data in an HTTP request.
If you don't set the content type, most clients will default to using'application/x-www-form-urlencoded', which may not be what you want.
As an example, if you are sendingjson encoded data using jQuery with the.ajax() method, you should make sure to include thecontentType: 'application/json' setting.
The default set of parsers may be set globally, using theDEFAULT_PARSER_CLASSES setting. For example, the following settings would allow only requests withJSON content, instead of the default of JSON or form data.
REST_FRAMEWORK = { 'DEFAULT_PARSER_CLASSES': [ 'rest_framework.parsers.JSONParser', ]}You can also set the parsers used for an individual view, or viewset,using theAPIView class-based views.
from rest_framework.parsers import JSONParserfrom rest_framework.response import Responsefrom rest_framework.views import APIViewclass ExampleView(APIView): """ A view that can accept POST requests with JSON content. """ parser_classes = [JSONParser] def post(self, request, format=None): return Response({'received data': request.data})Or, if you're using the@api_view decorator with function based views.
from rest_framework.decorators import api_viewfrom rest_framework.decorators import parser_classesfrom rest_framework.parsers import JSONParser@api_view(['POST'])@parser_classes([JSONParser])def example_view(request, format=None): """ A view that can accept POST requests with JSON content. """ return Response({'received data': request.data})ParsesJSON request content.request.data will be populated with a dictionary of data.
.media_type:application/json
Parses HTML form content.request.data will be populated with aQueryDict of data.
You will typically want to use bothFormParser andMultiPartParser together in order to fully support HTML form data.
.media_type:application/x-www-form-urlencoded
Parses multipart HTML form content, which supports file uploads.request.data andrequest.FILES will be populated with aQueryDict andMultiValueDict respectively.
You will typically want to use bothFormParser andMultiPartParser together in order to fully support HTML form data.
.media_type:multipart/form-data
Parses raw file upload content. Therequest.data property will be a dictionary with a single key'file' containing the uploaded file.
If the view used withFileUploadParser is called with afilename URL keyword argument, then that argument will be used as the filename.
If it is called without afilename URL keyword argument, then the client must set the filename in theContent-Disposition HTTP header. For exampleContent-Disposition: attachment; filename=upload.jpg.
.media_type:*/*
FileUploadParser is for usage with native clients that can upload the file as a raw data request. For web-based uploads, or for native clients with multipart upload support, you should use theMultiPartParser instead.media_type matches any content type,FileUploadParser should generally be the only parser set on an API view.FileUploadParser respects Django's standardFILE_UPLOAD_HANDLERS setting, and therequest.upload_handlers attribute. See theDjango documentation for more details.# views.pyclass FileUploadView(views.APIView): parser_classes = [FileUploadParser] def put(self, request, filename, format=None): file_obj = request.data['file'] # ... # do some stuff with uploaded file # ... return Response(status=204)# urls.pyurlpatterns = [ # ... re_path(r'^upload/(?P<filename>[^/]+)$', FileUploadView.as_view())]To implement a custom parser, you should overrideBaseParser, set the.media_type property, and implement the.parse(self, stream, media_type, parser_context) method.
The method should return the data that will be used to populate therequest.data property.
The arguments passed to.parse() are:
A stream-like object representing the body of the request.
Optional. If provided, this is the media type of the incoming request content.
Depending on the request'sContent-Type: header, this may be more specific than the renderer'smedia_type attribute, and may include media type parameters. For example"text/plain; charset=utf-8".
Optional. If supplied, this argument will be a dictionary containing any additional context that may be required to parse the request content.
By default this will include the following keys:view,request,args,kwargs.
The following is an example plaintext parser that will populate therequest.data property with a string representing the body of the request.
class PlainTextParser(BaseParser): """ Plain text parser. """ media_type = 'text/plain' def parse(self, stream, media_type=None, parser_context=None): """ Simply return a string representing the body of the request. """ return stream.read()The following third party packages are also available.
REST framework YAML providesYAML parsing and rendering support. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.
Install using pip.
$ pip install djangorestframework-yamlModify your REST framework settings.
REST_FRAMEWORK = { 'DEFAULT_PARSER_CLASSES': [ 'rest_framework_yaml.parsers.YAMLParser', ], 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_yaml.renderers.YAMLRenderer', ],}REST Framework XML provides a simple informal XML format. It was previously included directly in the REST framework package, and is now instead supported as a third-party package.
Install using pip.
$ pip install djangorestframework-xmlModify your REST framework settings.
REST_FRAMEWORK = { 'DEFAULT_PARSER_CLASSES': [ 'rest_framework_xml.parsers.XMLParser', ], 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework_xml.renderers.XMLRenderer', ],}MessagePack is a fast, efficient binary serialization format.Juan Riaza maintains thedjangorestframework-msgpack package which provides MessagePack renderer and parser support for REST framework.
djangorestframework-camel-case provides camel case JSON renderers and parsers for REST framework. This allows serializers to use Python-style underscored field names, but be exposed in the API as Javascript-style camel case field names. It is maintained byVitaly Babiy.