When designing an API, an important component is defining the representation
of the data you're presenting. Like Django models, you can control the
representation of a Resource
using fields. There are a variety of fields
for various types of data.
For the impatient:
import datetime from tastypie import fields from tastypie.resources import Resource from myapp.api.resources import ProfileResource, NoteResource class PersonResource(Resource): name = fields.CharField(attribute='name') age = fields.IntegerField(attribute='years_old', null=True) created = fields.DateTimeField(readonly=True, help_text='When the person was created', default=datetime.datetime.now) is_active = fields.BooleanField(default=True) profile = fields.ToOneField(ProfileResource, 'profile') notes = fields.ToManyField(NoteResource, 'notes', full=True)
All standard data fields have a common base class ApiField
which handles
the basic implementation details.
Note
You should not use the ApiField
class directly. Please use one of the
subclasses that is more correct for your data.
All ApiField
objects accept the following options.
.. attribute:: ApiField.attribute
A string naming an instance attribute of the object wrapped by the Resource. The
attribute will be accessed during the dehydrate
or or written during the hydrate
.
Defaults to None
, meaning data will be manually accessed.
.. attribute:: ApiField.default
Provides default data when the object being dehydrated
/hydrated
has no data on
the field.
Defaults to tastypie.fields.NOT_PROVIDED
.
.. attribute:: ApiField.null
Indicates whether or not a None
is allowable data on the field. Defaults to
False
.
.. attribute:: ApiField.readonly
Indicates whether the field is used during the hydrate
or not. Defaults to False
.
.. attribute:: ApiField.unique
Indicates whether the field is a unique identifier for the object.
.. attribute:: ApiField.help_text
A human-readable description of the field exposed at the schema level. Defaults to the per-Field definition.
.. module:: tastypie.fields
A boolean field.
Covers both models.BooleanField
and models.NullBooleanField
.
A text field of arbitrary length.
Covers both models.CharField
and models.TextField
.
A date field.
A datetime field.
A decimal field.
A dictionary field.
A file-related field.
Covers both models.FileField
and models.ImageField
.
A floating point field.
An integer field.
Covers models.IntegerField
, models.PositiveIntegerField
,
models.PositiveSmallIntegerField
and models.SmallIntegerField
.
A list field.
Provides access to data that is related within the database.
The RelatedField
base class is not intended for direct use but provides
functionality that ToOneField
and ToManyField
build upon.
The contents of this field actually point to another Resource
,
rather than the related object. This allows the field to represent its data
in different ways.
The abstractions based around this are "leaky" in that, unlike the other
fields provided by tastypie
, these fields don't handle arbitrary objects
very well. The subclasses use Django's ORM layer to make things go, though
there is no ORM-specific code at this level.
In addition to the common attributes for all ApiField, relationship fields accept the following.
.. attribute:: RelatedField.to
The to
argument should point to a Resource
class, NOT to a Model
.
Required.
.. attribute:: RelatedField.full
Indicates how the related Resource
will appear post-dehydrate
. If
False
, the related Resource
will appear as a URL to the endpoint of
that resource. If True
, the result of the sub-resource's dehydrate
will
be included in full.
.. attribute:: RelatedField.related_name
Currently unused, as unlike Django's ORM layer, reverse relations between
Resource
classes are not automatically created. Defaults to None
.
Provides access to related data via foreign key.
This subclass requires Django's ORM layer to work properly.
An alias to ToOneField
for those who prefer to mirror django.db.models
.
An alias to ToOneField
for those who prefer to mirror django.db.models
.
Provides access to related data via a join table.
This subclass requires Django's ORM layer to work properly.
This field also has special behavior when dealing with attribute
in that
it can take a callable. For instance, if you need to filter the reverse
relation, you can do something like:
subjects = fields.ToManyField(SubjectResource, ToManyField(SubjectResource, attribute=lambda bundle: Subject.objects.filter(notes=bundle.obj, name__startswith='Personal'))
Note that the hydrate
portions of this field are quite different than
any other field. hydrate_m2m
actually handles the data and relations.
This is due to the way Django implements M2M relationships.
An alias to ToManyField
for those who prefer to mirror django.db.models
.
An alias to ToManyField
for those who prefer to mirror django.db.models
.