mirror of
https://github.com/encode/django-rest-framework.git
synced 2024-12-04 15:34:05 +03:00
306 lines
19 KiB
HTML
306 lines
19 KiB
HTML
<!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>
|
|
<link href="http://tomchristie.github.com/django-rest-framework/img/favicon.ico" rel="icon" type="image/x-icon">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta name="description" content="">
|
|
<meta name="author" content="">
|
|
|
|
<!-- Le styles -->
|
|
<link href="http://tomchristie.github.com/django-rest-framework/css/prettify.css" rel="stylesheet">
|
|
<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">
|
|
<link href="http://tomchristie.github.com/django-rest-framework/css/default.css" rel="stylesheet">
|
|
|
|
<!-- 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]-->
|
|
<body onload="prettyPrint()" class="fields-page">
|
|
|
|
<div class="wrapper">
|
|
|
|
<div class="navbar navbar-inverse navbar-fixed-top">
|
|
<div class="navbar-inner">
|
|
<div class="container-fluid">
|
|
<a class="repo-link btn btn-primary btn-small" href="https://github.com/tomchristie/django-rest-framework/tree/restframework2">GitHub</a>
|
|
<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>
|
|
<a class="brand" href="http://tomchristie.github.com/django-rest-framework">Django REST framework</a>
|
|
<div class="nav-collapse collapse">
|
|
<ul class="nav">
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework">Home</a></li>
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorial <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/quickstart">Quickstart</a></li>
|
|
<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>
|
|
<!-- <li><a href="http://tomchristie.github.com/django-rest-framework/tutorial/6-resource-orientated-projects">6 - Resource orientated projects</a></li> -->
|
|
</ul>
|
|
</li>
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Guide <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
<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>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/generic-views">Generic views</a></li>
|
|
<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>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/fields">Serializer fields</a></li>
|
|
<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>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/pagination">Pagination</a></li>
|
|
<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>
|
|
<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>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/api-guide/settings">Settings</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="dropdown">
|
|
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Topics <b class="caret"></b></a>
|
|
<ul class="dropdown-menu">
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/csrf">Working with AJAX and CSRF</a></li>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/browser-enhancements">Browser enhancements</a></li>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/browsable-api">The Browsable API</a></li>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/rest-hypermedia-hateoas">REST, Hypermedia & HATEOAS</a></li>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/contributing">Contributing to REST framework</a></li>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/migration">2.0 Migration Guide</a></li>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/release-notes">Release Notes</a></li>
|
|
<li><a href="http://tomchristie.github.com/django-rest-framework/topics/credits">Credits</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<ul class="nav pull-right">
|
|
<!-- TODO
|
|
<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>
|
|
-->
|
|
</ul>
|
|
</div><!--/.nav-collapse -->
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="body-content">
|
|
<div class="container-fluid">
|
|
<div class="row-fluid">
|
|
|
|
<div class="span3">
|
|
<!-- 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>
|
|
-->
|
|
<div id="table-of-contents">
|
|
<ul class="nav nav-list side-nav well sidebar-nav-fixed">
|
|
<li class="main"><a href="#serializer-fields">Serializer fields</a></li>
|
|
<li class="main"><a href="#generic-fields">Generic Fields</a></li>
|
|
<li><a href="#field">Field</a></li>
|
|
<li><a href="#writablefield">WritableField</a></li>
|
|
<li><a href="#modelfield">ModelField</a></li>
|
|
<li class="main"><a href="#typed-fields">Typed Fields</a></li>
|
|
<li><a href="#booleanfield">BooleanField</a></li>
|
|
<li><a href="#charfield">CharField</a></li>
|
|
<li><a href="#emailfield">EmailField</a></li>
|
|
<li><a href="#datefield">DateField</a></li>
|
|
<li><a href="#datetimefield">DateTimeField</a></li>
|
|
<li><a href="#integerfield">IntegerField</a></li>
|
|
<li><a href="#floatfield">FloatField</a></li>
|
|
<li class="main"><a href="#relational-fields">Relational Fields</a></li>
|
|
<li><a href="#relatedfield">RelatedField</a></li>
|
|
<li><a href="#manyrelatedfield">ManyRelatedField</a></li>
|
|
<li><a href="#primarykeyrelatedfield">PrimaryKeyRelatedField</a></li>
|
|
<li><a href="#manyprimarykeyrelatedfield">ManyPrimaryKeyRelatedField</a></li>
|
|
<li><a href="#hyperlinkedrelatedfield">HyperlinkedRelatedField</a></li>
|
|
<li><a href="#manyhyperlinkedrelatedfield">ManyHyperlinkedRelatedField</a></li>
|
|
<li><a href="#hyperlinkedidentityfield">HyperLinkedIdentityField</a></li>
|
|
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<div id="main-content" class="span9">
|
|
<p><a class="github" href="https://github.com/tomchristie/django-rest-framework/blob/restframework2/rest_framework/fields.py"><span class="label label-info">fields.py</span></a></p>
|
|
<h1 id="serializer-fields">Serializer fields</h1>
|
|
<blockquote>
|
|
<p>Flat is better than nested.</p>
|
|
<p>— <a href="http://www.python.org/dev/peps/pep-0020/">The Zen of Python</a></p>
|
|
</blockquote>
|
|
<p>Serializer fields handle converting between primative values and internal datatypes. They also deal with validating input values, as well as retrieving and setting the values from their parent objects.</p>
|
|
<hr />
|
|
<p><strong>Note:</strong> The serializer fields are declared in fields.py, but by convention you should import them using <code>from rest_framework import serializers</code> and refer to fields as <code>serializers.<FieldName></code>.</p>
|
|
<hr />
|
|
<h1 id="generic-fields">Generic Fields</h1>
|
|
<p>These generic fields are used for representing arbitrary model fields or the output of model methods.</p>
|
|
<h2 id="field">Field</h2>
|
|
<p>A generic, <strong>read-only</strong> field. You can use this field for any attribute that does not need to support write operations.</p>
|
|
<p>For example, using the following model.</p>
|
|
<pre class="prettyprint lang-py"><code>class Account(models.Model):
|
|
owner = models.ForeignKey('auth.user')
|
|
name = models.CharField(max_length=100)
|
|
created = models.DateTimeField(auto_now_add=True)
|
|
payment_expiry = models.DateTimeField()
|
|
|
|
def has_expired(self):
|
|
now = datetime.datetime.now()
|
|
return now > self.payment_expiry
|
|
</code></pre>
|
|
<p>A serializer definition that looked like this:</p>
|
|
<pre class="prettyprint lang-py"><code>class AccountSerializer(serializers.HyperlinkedModelSerializer):
|
|
expired = Field(source='has_expired')
|
|
|
|
class Meta:
|
|
fields = ('url', 'owner', 'name', 'expired')
|
|
</code></pre>
|
|
<p>Would produced output similar to:</p>
|
|
<pre class="prettyprint lang-py"><code>{
|
|
'url': 'http://example.com/api/accounts/3/',
|
|
'owner': 'http://example.com/api/users/12/',
|
|
'name': 'FooCorp business account',
|
|
'expired': True
|
|
}
|
|
</code></pre>
|
|
<p>Be default, the <code>Field</code> class will perform a basic translation of the source value into primative datatypes, falling back to unicode representations of complex datatypes when neccesary.</p>
|
|
<p>You can customize this behaviour by overriding the <code>.to_native(self, value)</code> method.</p>
|
|
<h2 id="writablefield">WritableField</h2>
|
|
<p>A field that supports both read and write operations. By itself <code>WriteableField</code> does not perform any translation of input values into a given type. You won't typically use this field directly, but you may want to override it and implement the <code>.to_native(self, value)</code> and <code>.from_native(self, value)</code> methods.</p>
|
|
<h2 id="modelfield">ModelField</h2>
|
|
<p>A generic field that can be tied to any arbitrary model field. The <code>ModelField</code> class delegates the task of serialization/deserialization to it's associated model field. This field can be used to create serializer fields for custom model fields, without having to create a new custom serializer field.</p>
|
|
<p><strong>Signature:</strong> <code>ModelField(model_field=<Django ModelField class>)</code></p>
|
|
<hr />
|
|
<h1 id="typed-fields">Typed Fields</h1>
|
|
<p>These fields represent basic datatypes, and support both reading and writing values.</p>
|
|
<h2 id="booleanfield">BooleanField</h2>
|
|
<p>A Boolean representation, corresponds to <code>django.db.models.fields.BooleanField</code>.</p>
|
|
<h2 id="charfield">CharField</h2>
|
|
<p>A text representation, optionally validates the text to be shorter than <code>max_length</code> and longer than <code>min_length</code>, corresponds to <code>django.db.models.fields.CharField</code>
|
|
or <code>django.db.models.fields.TextField</code>.</p>
|
|
<p><strong>Signature:</strong> <code>CharField([max_length=<Integer>[, min_length=<Integer>]])</code></p>
|
|
<h2 id="emailfield">EmailField</h2>
|
|
<p>A text representation, validates the text to be a valid e-mail adress. Corresponds to <code>django.db.models.fields.EmailField</code></p>
|
|
<h2 id="datefield">DateField</h2>
|
|
<p>A date representation. Corresponds to <code>django.db.models.fields.DateField</code></p>
|
|
<h2 id="datetimefield">DateTimeField</h2>
|
|
<p>A date and time representation. Corresponds to <code>django.db.models.fields.DateTimeField</code></p>
|
|
<h2 id="integerfield">IntegerField</h2>
|
|
<p>An integer representation. Corresponds to <code>django.db.models.fields.IntegerField</code>, <code>django.db.models.fields.SmallIntegerField</code>, <code>django.db.models.fields.PositiveIntegerField</code> and <code>django.db.models.fields.PositiveSmallIntegerField</code></p>
|
|
<h2 id="floatfield">FloatField</h2>
|
|
<p>A floating point representation. Corresponds to <code>django.db.models.fields.FloatField</code>.</p>
|
|
<hr />
|
|
<h1 id="relational-fields">Relational Fields</h1>
|
|
<p>Relational fields are used to represent model relationships. They can be applied to <code>ForeignKey</code>, <code>ManyToManyField</code> and <code>OneToOneField</code> relationships, as well as to reverse relationships, and custom relationships such as <code>GenericForeignKey</code>.</p>
|
|
<h2 id="relatedfield">RelatedField</h2>
|
|
<p>This field can be applied to any of the following:</p>
|
|
<ul>
|
|
<li>A <code>ForeignKey</code> field.</li>
|
|
<li>A <code>OneToOneField</code> field.</li>
|
|
<li>A reverse OneToOne relationship</li>
|
|
<li>Any other "to-one" relationship.</li>
|
|
</ul>
|
|
<p>By default <code>RelatedField</code> will represent the target of the field using it's <code>__unicode__</code> method.</p>
|
|
<p>You can customise this behaviour by subclassing <code>ManyRelatedField</code>, and overriding the <code>.to_native(self, value)</code> method.</p>
|
|
<h2 id="manyrelatedfield">ManyRelatedField</h2>
|
|
<p>This field can be applied to any of the following:</p>
|
|
<ul>
|
|
<li>A <code>ManyToManyField</code> field.</li>
|
|
<li>A reverse ManyToMany relationship.</li>
|
|
<li>A reverse ForeignKey relationship</li>
|
|
<li>Any other "to-many" relationship.</li>
|
|
</ul>
|
|
<p>By default <code>ManyRelatedField</code> will represent the targets of the field using their <code>__unicode__</code> method.</p>
|
|
<p>For example, given the following models:</p>
|
|
<pre class="prettyprint lang-py"><code>class TaggedItem(models.Model):
|
|
"""
|
|
Tags arbitrary model instances using a generic relation.
|
|
|
|
See: https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/
|
|
"""
|
|
tag = models.SlugField()
|
|
content_type = models.ForeignKey(ContentType)
|
|
object_id = models.PositiveIntegerField()
|
|
content_object = GenericForeignKey('content_type', 'object_id')
|
|
|
|
def __unicode__(self):
|
|
return self.tag
|
|
|
|
class Bookmark(models.Model):
|
|
"""
|
|
A bookmark consists of a URL, and 0 or more descriptive tags.
|
|
"""
|
|
url = models.URLField()
|
|
tags = GenericRelation(TaggedItem)
|
|
</code></pre>
|
|
<p>And a model serializer defined like this:</p>
|
|
<pre class="prettyprint lang-py"><code>class BookmarkSerializer(serializers.ModelSerializer):
|
|
tags = serializers.ManyRelatedField(source='tags')
|
|
|
|
class Meta:
|
|
model = Bookmark
|
|
exclude = ('id',)
|
|
</code></pre>
|
|
<p>The an example output format for a Bookmark instance would be:</p>
|
|
<pre class="prettyprint lang-py"><code>{
|
|
'tags': [u'django', u'python'],
|
|
'url': u'https://www.djangoproject.com/'
|
|
}
|
|
</code></pre>
|
|
<h2 id="primarykeyrelatedfield">PrimaryKeyRelatedField</h2>
|
|
<p>As with <code>RelatedField</code> field can be applied to any "to-one" relationship, such as a <code>ForeignKey</code> field.</p>
|
|
<p><code>PrimaryKeyRelatedField</code> will represent the target of the field using it's primary key.</p>
|
|
<p>Be default, <code>PrimaryKeyRelatedField</code> is read-write, although you can change this behaviour using the <code>readonly</code> flag.</p>
|
|
<h2 id="manyprimarykeyrelatedfield">ManyPrimaryKeyRelatedField</h2>
|
|
<p>As with <code>RelatedField</code> field can be applied to any "to-many" relationship, such as a <code>ManyToManyField</code> field, or a reverse <code>ForeignKey</code> relationship.</p>
|
|
<p><code>PrimaryKeyRelatedField</code> will represent the target of the field using their primary key.</p>
|
|
<p>Be default, <code>ManyPrimaryKeyRelatedField</code> is read-write, although you can change this behaviour using the <code>readonly</code> flag.</p>
|
|
<h2 id="hyperlinkedrelatedfield">HyperlinkedRelatedField</h2>
|
|
<h2 id="manyhyperlinkedrelatedfield">ManyHyperlinkedRelatedField</h2>
|
|
<h2 id="hyperlinkedidentityfield">HyperLinkedIdentityField</h2>
|
|
</div><!--/span-->
|
|
</div><!--/row-->
|
|
</div><!--/.fluid-container-->
|
|
</div><!--/.body content-->
|
|
|
|
<div id="push"></div>
|
|
</div><!--/.wrapper -->
|
|
|
|
<footer class="span12">
|
|
<p>Sponsored by <a href="http://dabapps.com/">DabApps</a>.</a></p>
|
|
</footer>
|
|
|
|
<!-- Le javascript
|
|
================================================== -->
|
|
<!-- Placed at the end of the document so the pages load faster -->
|
|
<script src="http://tomchristie.github.com/django-rest-framework/js/jquery-1.8.1-min.js"></script>
|
|
<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>
|
|
<script>
|
|
//$('.side-nav').scrollspy()
|
|
var shiftWindow = function() { scrollBy(0, -50) };
|
|
if (location.hash) shiftWindow();
|
|
window.addEventListener("hashchange", shiftWindow);
|
|
|
|
$('.dropdown-menu').on('click touchstart', function(event) {
|
|
event.stopPropagation();
|
|
});
|
|
</script>
|
|
</body></html>
|