diff options
Diffstat (limited to 'docs/api-guide')
| -rw-r--r-- | docs/api-guide/fields.md | 44 | ||||
| -rw-r--r-- | docs/api-guide/serializers.md | 29 |
2 files changed, 47 insertions, 26 deletions
diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 8c3df067..411f7944 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -235,44 +235,50 @@ Then an example output format for a Bookmark instance would be: 'url': u'https://www.djangoproject.com/' } -## PrimaryKeyRelatedField +## PrimaryKeyRelatedField / ManyPrimaryKeyRelatedField -This field can be applied to any "to-one" relationship, such as a `ForeignKey` field. +`PrimaryKeyRelatedField` and `ManyPrimaryKeyRelatedField` will represent the target of the relationship using it's primary key. -`PrimaryKeyRelatedField` will represent the target of the field using it's primary key. +By default these fields are read-write, although you can change this behaviour using the `read_only` flag. -Be default, `PrimaryKeyRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +**Arguments**: -## ManyPrimaryKeyRelatedField +* `queryset` - By default `ModelSerializer` classes will use the default queryset for the relationship. `Serializer` classes must either set a queryset explicitly, or set `read_only=True`. -This field can be applied to any "to-many" relationship, such as a `ManyToManyField` field, or a reverse `ForeignKey` relationship. +## SlugRelatedField / ManySlugRelatedField -`PrimaryKeyRelatedField` will represent the targets of the field using their primary key. +`SlugRelatedField` and `ManySlugRelatedField` will represent the target of the relationship using a unique slug. -Be default, `ManyPrimaryKeyRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +By default these fields read-write, although you can change this behaviour using the `read_only` flag. -## HyperlinkedRelatedField +**Arguments**: -This field can be applied to any "to-one" relationship, such as a `ForeignKey` field. +* `slug_field` - The field on the target that should be used to represent it. This should be a field that uniquely identifies any given instance. For example, `username`. +* `queryset` - By default `ModelSerializer` classes will use the default queryset for the relationship. `Serializer` classes must either set a queryset explicitly, or set `read_only=True`. -`HyperlinkedRelatedField` will represent the target of the field using a hyperlink. You must include a named URL pattern in your URL conf, with a name like `'{model-name}-detail'` that corresponds to the target of the hyperlink. +## HyperlinkedRelatedField / ManyHyperlinkedRelatedField -Be default, `HyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +`HyperlinkedRelatedField` and `ManyHyperlinkedRelatedField` will represent the target of the relationship using a hyperlink. -## ManyHyperlinkedRelatedField +By default, `HyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. -This field can be applied to any "to-many" relationship, such as a `ManyToManyField` field, or a reverse `ForeignKey` relationship. +**Arguments**: -`ManyHyperlinkedRelatedField` will represent the targets of the field using hyperlinks. You must include a named URL pattern in your URL conf, with a name like `'{model-name}-detail'` that corresponds to the target of the hyperlink. - -Be default, `ManyHyperlinkedRelatedField` is read-write, although you can change this behaviour using the `read_only` flag. +* `view_name` - The view name that should be used as the target of the relationship. **required**. +* `format` - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the `format` argument. +* `queryset` - By default `ModelSerializer` classes will use the default queryset for the relationship. `Serializer` classes must either set a queryset explicitly, or set `read_only=True`. +* `slug_field` - The field on the target that should be used for the lookup. Default is `'slug'`. +* `slug_url_kwarg` - The named url parameter for the slug field lookup. Default is to use the same value as given for `slug_field`. ## HyperLinkedIdentityField This field can be applied as an identity relationship, such as the `'url'` field on a HyperlinkedModelSerializer. -You must include a named URL pattern in your URL conf, with a name like `'{model-name}-detail'` that corresponds to the model. - This field is always read-only. +**Arguments**: + +* `view_name` - The view name that should be used as the target of the relationship. **required**. +* `format` - If using format suffixes, hyperlinked fields will use the same format suffix for the target unless overridden by using the `format` argument. + [cite]: http://www.python.org/dev/peps/pep-0020/ diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index c88b9b0c..ee7f72dd 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -47,7 +47,7 @@ The first part of serializer class defines the fields that get serialized/deseri We can now use `CommentSerializer` to serialize a comment, or list of comments. Again, using the `Serializer` class looks a lot like using a `Form` class. - serializer = CommentSerializer(instance=comment) + serializer = CommentSerializer(comment) serializer.data # {'email': u'leila@example.com', 'content': u'foo bar', 'created': datetime.datetime(2012, 8, 22, 16, 20, 9, 822774)} @@ -65,20 +65,29 @@ Deserialization is similar. First we parse a stream into python native datatype ...then we restore those native datatypes into a fully populated object instance. - serializer = CommentSerializer(data) + serializer = CommentSerializer(data=data) serializer.is_valid() # True serializer.object # <Comment object at 0x10633b2d0> >>> serializer.deserialize('json', stream) +When deserializing data, we can either create a new instance, or update an existing instance. + + serializer = CommentSerializer(data=data) # Create new instance + serializer = CommentSerializer(comment, data=data) # Update `instance` + ## Validation When deserializing data, you always need to call `is_valid()` before attempting to access the deserialized object. If any validation errors occur, the `.errors` and `.non_field_errors` properties will contain the resulting error messages. ### Field-level validation -You can specify custom field-level validation by adding `validate_<fieldname>()` methods to your `Serializer` subclass. These are analagous to `clean_<fieldname>` methods on Django forms, but accept slightly different arguments. They take a dictionary of deserialized attributes as a first argument, and the field name in that dictionary as a second argument (which will be either the name of the field or the value of the `source` argument to the field, if one was provided). Your `validate_<fieldname>` methods should either just return the attrs dictionary or raise a `ValidationError`. For example: +You can specify custom field-level validation by adding `.validate_<fieldname>` methods to your `Serializer` subclass. These are analagous to `.clean_<fieldname>` methods on Django forms, but accept slightly different arguments. + +They take a dictionary of deserialized attributes as a first argument, and the field name in that dictionary as a second argument (which will be either the name of the field or the value of the `source` argument to the field, if one was provided). + +Your `validate_<fieldname>` methods should either just return the `attrs` dictionary or raise a `ValidationError`. For example: from rest_framework import serializers @@ -88,16 +97,22 @@ You can specify custom field-level validation by adding `validate_<fieldname>()` def validate_title(self, attrs, source): """ - Check that the blog post is about Django + Check that the blog post is about Django. """ value = attrs[source] - if "Django" not in value: + if "django" not in value.lower(): raise serializers.ValidationError("Blog post is not about Django") return attrs -### Final cross-field validation +### Object-level validation + +To do any other validation that requires access to multiple fields, add a method called `.validate()` to your `Serializer` subclass. This method takes a single argument, which is the `attrs` dictionary. It should raise a `ValidationError` if necessary, or just return `attrs`. + +## Saving object state + +Serializers also include a `.save()` method that you can override if you want to provide a method of persisting the state of a deserialized object. The default behavior of the method is to simply call `.save()` on the deserialized object instance. -To do any other validation that requires access to multiple fields, add a method called `validate` to your `Serializer` subclass. This method takes a single argument, which is the `attrs` dictionary. It should raise a `ValidationError` if necessary, or just return `attrs`. +The generic views provided by REST framework call the `.save()` method when updating or creating entities. ## Dealing with nested objects |