diff options
Diffstat (limited to 'docs/api-guide')
| -rw-r--r-- | docs/api-guide/fields.md | 8 | ||||
| -rw-r--r-- | docs/api-guide/serializers.md | 42 | ||||
| -rw-r--r-- | docs/api-guide/settings.md | 6 |
3 files changed, 55 insertions, 1 deletions
diff --git a/docs/api-guide/fields.md b/docs/api-guide/fields.md index 91866664..c136509b 100644 --- a/docs/api-guide/fields.md +++ b/docs/api-guide/fields.md @@ -28,7 +28,13 @@ Defaults to the name of the field. ### `read_only` -Set this to `True` to ensure that the field is used when serializing a representation, but is not used when updating an instance during deserialization. +Set this to `True` to ensure that the field is used when serializing a representation, but is not used when creating or updating an instance during deserialization. + +Defaults to `False` + +### `write_only` + +Set this to `True` to ensure that the field may be used when updating or creating an instance, but is not included when serializing the representation. Defaults to `False` diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md index 04439092..e8369c20 100644 --- a/docs/api-guide/serializers.md +++ b/docs/api-guide/serializers.md @@ -373,6 +373,25 @@ You may wish to specify multiple fields as read-only. Instead of adding each fi Model fields which have `editable=False` set, and `AutoField` fields will be set to read-only by default, and do not need to be added to the `read_only_fields` option. +## Specifying which fields should be write-only + +You may wish to specify multiple fields as write-only. Instead of adding each field explicitly with the `write_only=True` attribute, you may use the `write_only_fields` Meta option, like so: + + class CreateUserSerializer(serializers.ModelSerializer): + class Meta: + model = User + fields = ('email', 'username', 'password') + write_only_fields = ('password',) # Note: Password field is write-only + + def restore_object(self, attrs, instance=None): + """ + Instantiate a new User instance. + """ + assert instance is None, 'Cannot update users with CreateUserSerializer' + user = User(email=attrs['email'], username=attrs['username']) + user.set_password(attrs['password']) + return user + ## Specifying fields explicitly You can add extra fields to a `ModelSerializer` or override the default fields by declaring fields on the class, just as you would for a `Serializer` class. @@ -445,6 +464,29 @@ For more specific requirements such as specifying a different lookup for each fi model = Account fields = ('url', 'account_name', 'users', 'created') +## Overiding the URL field behavior + +The name of the URL field defaults to 'url'. You can override this globally, by using the `URL_FIELD_NAME` setting. + +You can also override this on a per-serializer basis by using the `url_field_name` option on the serializer, like so: + + class AccountSerializer(serializers.HyperlinkedModelSerializer): + class Meta: + model = Account + fields = ('account_url', 'account_name', 'users', 'created') + url_field_name = 'account_url' + +**Note**: The generic view implementations normally generate a `Location` header in response to successful `POST` requests. Serializers using `url_field_name` option will not have this header automatically included by the view. If you need to do so you will ned to also override the view's `get_success_headers()` method. + +You can also overide the URL field's view name and lookup field without overriding the field explicitly, by using the `view_name` and `lookup_field` options, like so: + + class AccountSerializer(serializers.HyperlinkedModelSerializer): + class Meta: + model = Account + fields = ('account_url', 'account_name', 'users', 'created') + view_name = 'account_detail' + lookup_field='account_name' + --- # Advanced serializer usage diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md index 13f96f9a..5aee52aa 100644 --- a/docs/api-guide/settings.md +++ b/docs/api-guide/settings.md @@ -353,6 +353,12 @@ This should be a function with the following signature: Default: `'rest_framework.views.exception_handler'` +#### URL_FIELD_NAME + +A string representing the key that should be used for the URL fields generated by `HyperlinkedModelSerializer`. + +Default: `'url'` + #### FORMAT_SUFFIX_KWARG The name of a parameter in the URL conf that may be used to provide a format suffix. |