2012-09-02 00:24:33 +04:00
<!DOCTYPE html>
< html lang = "en" > < head > < meta http-equiv = "Content-Type" content = "text/html; charset=UTF-8" >
< meta charset = "utf-8" >
< title > Django REST framework< / title >
2012-10-05 18:26:53 +04:00
< link href = "http://tomchristie.github.com/django-rest-framework/img/favicon.ico" rel = "icon" type = "image/x-icon" >
2012-09-02 00:24:33 +04:00
< meta name = "viewport" content = "width=device-width, initial-scale=1.0" >
< meta name = "description" content = "" >
< meta name = "author" content = "" >
<!-- Le styles -->
2012-09-08 23:24:07 +04:00
< link href = "http://tomchristie.github.com/django-rest-framework/css/prettify.css" rel = "stylesheet" >
2012-09-02 00:37:41 +04:00
< link href = "http://tomchristie.github.com/django-rest-framework/css/bootstrap.css" rel = "stylesheet" >
< link href = "http://tomchristie.github.com/django-rest-framework/css/bootstrap-responsive.css" rel = "stylesheet" >
2012-09-13 12:40:09 +04:00
< link href = "http://tomchristie.github.com/django-rest-framework/css/default.css" rel = "stylesheet" >
2012-09-02 00:24:33 +04:00
<!-- Le HTML5 shim, for IE6 - 8 support of HTML5 elements -->
<!-- [if lt IE 9]>
< script src = "http://html5shim.googlecode.com/svn/trunk/html5.js" > < / script >
<![endif]-->
2012-10-01 19:27:59 +04:00
< body onload = "prettyPrint()" class = "parsers-page" >
2012-09-02 00:24:33 +04:00
2012-10-05 22:27:27 +04:00
< div class = "wrapper" >
2012-09-02 00:24:33 +04:00
< div class = "navbar navbar-inverse navbar-fixed-top" >
< div class = "navbar-inner" >
< div class = "container-fluid" >
2012-09-12 16:12:00 +04:00
< a class = "repo-link btn btn-primary btn-small" href = "https://github.com/tomchristie/django-rest-framework/tree/restframework2" > GitHub< / a >
2012-09-02 00:24:33 +04:00
< a class = "btn btn-navbar" data-toggle = "collapse" data-target = ".nav-collapse" >
< span class = "icon-bar" > < / span >
< span class = "icon-bar" > < / span >
< span class = "icon-bar" > < / span >
< / a >
2012-09-02 00:37:41 +04:00
< a class = "brand" href = "http://tomchristie.github.com/django-rest-framework" > Django REST framework< / a >
2012-09-02 00:24:33 +04:00
< div class = "nav-collapse collapse" >
< ul class = "nav" >
2012-09-02 00:37:41 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework" > Home< / a > < / li >
2012-09-02 00:24:33 +04:00
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > Tutorial < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
2012-10-09 15:01:56 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/tutorial/quickstart" > Quickstart< / a > < / li >
2012-09-02 00:37:41 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/tutorial/1-serialization" > 1 - Serialization< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/tutorial/2-requests-and-responses" > 2 - Requests and responses< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/tutorial/3-class-based-views" > 3 - Class based views< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/tutorial/4-authentication-permissions-and-throttling" > 4 - Authentication, permissions and throttling< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/tutorial/5-relationships-and-hyperlinked-apis" > 5 - Relationships and hyperlinked APIs< / a > < / li >
2012-10-10 12:36:47 +04:00
<!-- <li><a href="http://tomchristie.github.com/django - rest - framework/tutorial/6 - resource - orientated - projects">6 - Resource orientated projects</a></li> -->
2012-09-02 00:24:33 +04:00
< / ul >
< / li >
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > API Guide < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
2012-09-02 00:37:41 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/requests" > Requests< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/responses" > Responses< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/views" > Views< / a > < / li >
2012-09-12 13:14:01 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/generic-views" > Generic views< / a > < / li >
2012-09-02 00:37:41 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/parsers" > Parsers< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/renderers" > Renderers< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/serializers" > Serializers< / a > < / li >
2012-10-05 20:10:33 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/fields" > Serializer fields< / a > < / li >
2012-09-02 00:37:41 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/authentication" > Authentication< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/permissions" > Permissions< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/throttling" > Throttling< / a > < / li >
2012-10-01 19:27:59 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/pagination" > Pagination< / a > < / li >
2012-09-12 13:14:01 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/content-negotiation" > Content negotiation< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/format-suffixes" > Format suffixes< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/reverse" > Returning URLs< / a > < / li >
2012-09-02 00:37:41 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/exceptions" > Exceptions< / a > < / li >
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/status-codes" > Status codes< / a > < / li >
2012-09-05 16:05:36 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/api-guide/settings" > Settings< / a > < / li >
2012-09-02 00:24:33 +04:00
< / ul >
< / li >
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > Topics < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
2012-09-02 00:37:41 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/topics/csrf" > Working with AJAX and CSRF< / a > < / li >
2012-10-13 18:09:05 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/topics/browser-enhancements" > Browser enhancements< / a > < / li >
2012-10-13 18:35:46 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/topics/browsable-api" > The Browsable API< / a > < / li >
2012-10-08 15:19:26 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas" > REST, Hypermedia & HATEOAS< / a > < / li >
2012-09-05 16:05:36 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/topics/contributing" > Contributing to REST framework< / a > < / li >
2012-10-08 15:19:26 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/topics/migration" > 2.0 Migration Guide< / a > < / li >
2012-10-17 16:50:08 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/topics/release-notes" > Release Notes< / a > < / li >
2012-09-02 00:37:41 +04:00
< li > < a href = "http://tomchristie.github.com/django-rest-framework/topics/credits" > Credits< / a > < / li >
2012-09-02 00:24:33 +04:00
< / ul >
< / li >
< / ul >
< ul class = "nav pull-right" >
2012-10-09 17:13:19 +04:00
<!-- TODO
2012-09-08 11:03:30 +04:00
< li class = "dropdown" >
< a href = "#" class = "dropdown-toggle" data-toggle = "dropdown" > Version: 2.0.0 < b class = "caret" > < / b > < / a >
< ul class = "dropdown-menu" >
< li > < a href = "#" > Trunk< / a > < / li >
< li > < a href = "#" > 2.0.0< / a > < / li >
< / ul >
< / li >
2012-10-09 17:13:19 +04:00
-->
2012-09-08 11:03:30 +04:00
< / ul >
2012-09-02 00:24:33 +04:00
< / div > <!-- /.nav - collapse -->
< / div >
< / div >
< / div >
2012-10-05 22:27:27 +04:00
< div class = "body-content" >
< div class = "container-fluid" >
< div class = "row-fluid" >
2012-10-05 16:22:18 +04:00
2012-10-05 22:27:27 +04:00
< div class = "span3" >
2012-10-08 15:19:26 +04:00
<!-- TODO
< p style = "margin-top: -12px" >
< a class = "btn btn-mini btn-primary" style = "width: 60px" > « previous< / a >
< a class = "btn btn-mini btn-primary" style = "float: right; margin-right: 8px; width: 60px;" > next » < / a >
< / p >
-->
2012-10-05 22:27:27 +04:00
< div id = "table-of-contents" >
< ul class = "nav nav-list side-nav well sidebar-nav-fixed" >
< li class = "main" > < a href = "#parsers" > Parsers< / a > < / li >
2012-10-17 16:50:08 +04:00
< li > < a href = "#how-the-parser-is-determined" > How the parser is determined< / a > < / li >
< li > < a href = "#setting-the-parsers" > Setting the parsers< / a > < / li >
< li class = "main" > < a href = "#api-reference" > API Reference< / a > < / li >
2012-09-27 19:28:13 +04:00
< li > < a href = "#jsonparser" > JSONParser< / a > < / li >
< li > < a href = "#yamlparser" > YAMLParser< / a > < / li >
< li > < a href = "#xmlparser" > XMLParser< / a > < / li >
< li > < a href = "#formparser" > FormParser< / a > < / li >
< li > < a href = "#multipartparser" > MultiPartParser< / a > < / li >
2012-10-17 16:50:08 +04:00
< li class = "main" > < a href = "#custom-parsers" > Custom parsers< / a > < / li >
< li > < a href = "#example" > Example< / a > < / li >
< li > < a href = "#uploading-file-content" > Uploading file content< / a > < / li >
2012-09-02 00:24:33 +04:00
2012-10-05 22:27:27 +04:00
< / ul >
< / div >
2012-09-08 11:03:30 +04:00
< / div >
2012-09-02 00:24:33 +04:00
2012-10-05 22:27:27 +04:00
< div id = "main-content" class = "span9" >
< p > < a class = "github" href = "https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/parsers.py" > < span class = "label label-info" > parsers.py< / span > < / a > < / p >
2012-09-09 01:06:49 +04:00
< h1 id = "parsers" > Parsers< / h1 >
2012-09-27 19:28:13 +04:00
< blockquote >
< p > Machine interacting web services tend to use more
structured formats for sending data than form-encoded, since they're
sending more complex data than simple forms< / p >
< p > — Malcom Tredinnick, < a href = "https://groups.google.com/d/topic/django-developers/dxI4qVzrBY4/discussion" > Django developers group< / a > < / p >
< / blockquote >
2012-10-17 16:50:08 +04:00
< p > 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 flexiblity to design the media types that your API accepts.< / p >
< h2 id = "how-the-parser-is-determined" > How the parser is determined< / h2 >
< p > The set of valid parsers for a view is always defined as a list of classes. When either < code > request.DATA< / code > or < code > request.FILES< / code > is accessed, REST framework will examine the < code > Content-Type< / code > header on the incoming request, and determine which parser to use to parse the request content.< / p >
< h2 id = "setting-the-parsers" > Setting the parsers< / h2 >
2012-10-19 23:00:35 +04:00
< p > The default set of parsers may be set globally, using the < code > DEFAULT_PARSER_CLASSES< / code > setting. For example, the following settings would allow requests with < code > YAML< / code > content.< / p >
2012-10-17 16:50:08 +04:00
< pre class = "prettyprint lang-py" > < code > REST_FRAMEWORK = {
2012-10-19 23:00:35 +04:00
'DEFAULT_PARSER_CLASSES': (
2012-10-17 16:50:08 +04:00
'rest_framework.parsers.YAMLParser',
)
}
< / code > < / pre >
< p > You can also set the renderers used for an individual view, using the < code > APIView< / code > class based views.< / p >
< pre class = "prettyprint lang-py" > < code > class ExampleView(APIView):
"""
A view that can accept POST requests with YAML content.
"""
parser_classes = (YAMLParser,)
def post(self, request, format=None):
return Response({'received data': request.DATA})
< / code > < / pre >
< p > Or, if you're using the < code > @api_view< / code > decorator with function based views.< / p >
< pre class = "prettyprint lang-py" > < code > @api_view(('POST',)),
@parser_classes((YAMLParser,))
def example_view(request, format=None):
"""
A view that can accept POST requests with YAML content.
"""
return Response({'received data': request.DATA})
< / code > < / pre >
< hr / >
< h1 id = "api-reference" > API Reference< / h1 >
2012-09-27 19:28:13 +04:00
< h2 id = "jsonparser" > JSONParser< / h2 >
2012-10-17 16:50:08 +04:00
< p > Parses < code > JSON< / code > request content.< / p >
< p > < strong > .media_type< / strong > : < code > application/json< / code > < / p >
2012-09-27 19:28:13 +04:00
< h2 id = "yamlparser" > YAMLParser< / h2 >
2012-10-17 16:50:08 +04:00
< p > Parses < code > YAML< / code > request content.< / p >
< p > < strong > .media_type< / strong > : < code > application/yaml< / code > < / p >
2012-09-27 19:28:13 +04:00
< h2 id = "xmlparser" > XMLParser< / h2 >
2012-10-17 16:50:08 +04:00
< p > Parses REST framework's default style of < code > XML< / code > request content.< / p >
< p > Note that the < code > XML< / code > markup language is used typically used as the base language for more strictly defined domain-specific languages, such as < code > RSS< / code > , < code > Atom< / code > , and < code > XHTML< / code > .< / p >
< p > If you are considering using < code > XML< / code > 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.< / p >
< p > < strong > .media_type< / strong > : < code > application/xml< / code > < / p >
2012-09-27 19:28:13 +04:00
< h2 id = "formparser" > FormParser< / h2 >
2012-10-17 16:50:08 +04:00
< p > Parses HTML form content. < code > request.DATA< / code > will be populated with a < code > QueryDict< / code > of data, < code > request.FILES< / code > will be populated with an empty < code > QueryDict< / code > of data.< / p >
< p > You will typically want to use both < code > FormParser< / code > and < code > MultiPartParser< / code > together in order to fully support HTML form data.< / p >
< p > < strong > .media_type< / strong > : < code > application/x-www-form-urlencoded< / code > < / p >
2012-09-27 19:28:13 +04:00
< h2 id = "multipartparser" > MultiPartParser< / h2 >
2012-10-17 16:50:08 +04:00
< p > Parses multipart HTML form content, which supports file uploads. Both < code > request.DATA< / code > and < code > request.FILES< / code > will be populated with a < code > QueryDict< / code > .< / p >
< p > You will typically want to use both < code > FormParser< / code > and < code > MultiPartParser< / code > together in order to fully support HTML form data.< / p >
< p > < strong > .media_type< / strong > : < code > multipart/form-data< / code > < / p >
< hr / >
< h1 id = "custom-parsers" > Custom parsers< / h1 >
2012-10-19 23:00:35 +04:00
< p > To implement a custom parser, you should override < code > BaseParser< / code > , set the < code > .media_type< / code > property, and implement the < code > .parse(self, stream, media_type, parser_context)< / code > method.< / p >
2012-10-17 16:50:08 +04:00
< p > The method should return the data that will be used to populate the < code > request.DATA< / code > property.< / p >
2012-10-19 23:00:35 +04:00
< p > The arguments passed to < code > .parse()< / code > are:< / p >
2012-10-17 16:50:08 +04:00
< h3 id = "stream" > stream< / h3 >
< p > A stream-like object representing the body of the request.< / p >
2012-10-19 23:00:35 +04:00
< h3 id = "media_type" > media_type< / h3 >
< p > Optional. If provided, this is the media type of the incoming request content.< / p >
< p > Depending on the request's < code > Content-Type:< / code > header, this may be more specific than the renderer's < code > media_type< / code > attribute, and may include media type parameters. For example < code > "text/plain; charset=utf-8"< / code > .< / p >
2012-10-17 16:50:08 +04:00
< h3 id = "parser_context" > parser_context< / h3 >
2012-10-19 23:00:35 +04:00
< p > Optional. If supplied, this argument will be a dictionary containing any additional context that may be required to parse the request content.< / p >
< p > By default this will include the following keys: < code > view< / code > , < code > request< / code > , < code > args< / code > , < code > kwargs< / code > .< / p >
2012-10-17 16:50:08 +04:00
< h2 id = "example" > Example< / h2 >
< p > The following is an example plaintext parser that will populate the < code > request.DATA< / code > property with a string representing the body of the request. < / p >
< pre class = "prettyprint lang-py" > < code > class PlainTextParser(BaseParser):
"""
Plain text parser.
"""
media_type = 'text/plain'
2012-10-19 23:00:35 +04:00
def parse(self, stream, media_type=None, parser_context=None):
2012-10-17 16:50:08 +04:00
"""
Simply return a string representing the body of the request.
"""
return stream.read()
< / code > < / pre >
< h2 id = "uploading-file-content" > Uploading file content< / h2 >
2012-10-19 23:00:35 +04:00
< p > If your custom parser needs to support file uploads, you may return a < code > DataAndFiles< / code > object from the < code > .parse()< / code > method. < code > DataAndFiles< / code > should be instantiated with two arguments. The first argument will be used to populate the < code > request.DATA< / code > property, and the second argument will be used to populate the < code > request.FILES< / code > property.< / p >
2012-10-17 16:50:08 +04:00
< p > For example:< / p >
< pre class = "prettyprint lang-py" > < code > class SimpleFileUploadParser(BaseParser):
"""
A naive raw file upload parser.
"""
2012-10-19 23:00:35 +04:00
def parse(self, stream, media_type=None, parser_context=None):
2012-10-17 16:50:08 +04:00
content = stream.read()
name = 'example.dat'
content_type = 'application/octet-stream'
size = len(content)
charset = 'utf-8'
# Write a temporary file based on the request content
temp = tempfile.NamedTemporaryFile(delete=False)
temp.write(content)
uploaded = UploadedFile(temp, name, content_type, size, charset)
# Return the uploaded file
data = {}
files = {name: uploaded}
return DataAndFiles(data, files)
< / code > < / pre >
2012-10-05 22:27:27 +04:00
< / div > <!-- /span -->
< / div > <!-- /row -->
< / div > <!-- /.fluid - container -->
< / div > <!-- /.body content -->
2012-09-02 00:24:33 +04:00
2012-10-05 18:26:53 +04:00
< div id = "push" > < / div >
2012-10-05 22:27:27 +04:00
< / div > <!-- /.wrapper -->
2012-10-05 18:26:53 +04:00
2012-10-05 22:27:27 +04:00
< footer class = "span12" >
2012-10-05 22:33:52 +04:00
< p > Sponsored by < a href = "http://dabapps.com/" > DabApps< / a > .< / a > < / p >
2012-10-05 22:27:27 +04:00
< / footer >
2012-10-05 18:26:53 +04:00
2012-09-02 00:24:33 +04:00
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
2012-09-08 11:03:30 +04:00
< script src = "http://tomchristie.github.com/django-rest-framework/js/jquery-1.8.1-min.js" > < / script >
2012-10-05 16:22:18 +04:00
< script src = "http://tomchristie.github.com/django-rest-framework/js/prettify-1.0.js" > < / script >
< script src = "http://tomchristie.github.com/django-rest-framework/js/bootstrap-2.1.1-min.js" > < / script >
2012-09-02 00:24:33 +04:00
< script >
2012-09-08 11:03:30 +04:00
//$('.side-nav').scrollspy()
var shiftWindow = function() { scrollBy(0, -50) };
if (location.hash) shiftWindow();
window.addEventListener("hashchange", shiftWindow);
2012-09-12 13:14:01 +04:00
2012-09-17 23:21:26 +04:00
$('.dropdown-menu').on('click touchstart', function(event) {
2012-09-12 13:14:01 +04:00
event.stopPropagation();
});
2012-09-02 00:24:33 +04:00
< / script >
2012-10-01 19:27:59 +04:00
< / body > < / html >
