More HyperlinkedModelSerializer docs

2 files changed, 29 insertions, 0 deletions

diff --git a/docs/api-guide/serializers.md b/docs/api-guide/serializers.md
index b05acfd5..e8369c20 100644
--- a/docs/api-guide/serializers.md
+++ b/docs/api-guide/serializers.md
@@ -464,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.