diff --git a/docs/advanced_topics/api/v2/configuration.rst b/docs/advanced_topics/api/v2/configuration.rst index 64a3cea9dd..0e669aef3e 100644 --- a/docs/advanced_topics/api/v2/configuration.rst +++ b/docs/advanced_topics/api/v2/configuration.rst @@ -111,11 +111,15 @@ For example: # blog/models.py + from wagtail.api import APIField + class BlogPageAuthor(Orderable): page = models.ForeignKey('blog.BlogPage', related_name='authors') name = models.CharField(max_length=255) - api_fields = ['name'] + api_fields = [ + APIField('name'), + ] class BlogPage(Page): @@ -126,10 +130,10 @@ For example: # Export fields over the API api_fields = [ - 'published_date', - 'body', - 'feed_image', - 'authors', # This will nest the relevant BlogPageAuthor objects in the API response + APIField('published_date'), + APIField('body'), + APIField('feed_image'), + APIField('authors'), # This will nest the relevant BlogPageAuthor objects in the API response ] This will make ``published_date``, ``body``, ``feed_image`` and a list of @@ -137,6 +141,111 @@ This will make ``published_date``, ``body``, ``feed_image`` and a list of fields, you must select the ``blog.BlogPage`` type using the ``?type`` :ref:`parameter in the API itself `. +Custom serialisers +------------------ + +.. versionadded: 1.10 + +Serialisers_ are used to convert the database representation of a model into +something that can be sent over the wire in JSON format. You can override the +serialiser for any field using the ``serializer`` keyword argument: + +.. code-block:: python + + from rest_framework.fields import DateField + + class BlogPage(Page): + ... + + api_fields = [ + # Change the format of the published_date field to "Thursday 06 April 2017" + APIField('published_date', serializer=DateField(format='%A $d %B %Y')), + ... + ] + +Django REST framework's serializers can all take a source_ argument allowing you +to add API fields that have a different field name or no underlying field at all: + +.. code-block:: python + + from rest_framework.fields import DateField + + class BlogPage(Page): + ... + + api_fields = [ + # Date in ISO8601 format (the default) + APIField('published_date'), + + # A separate published_date_display field with a different format + APIField('published_date_display', serializer=DateField(format='%A $d %B %Y', source='published_date')), + ... + ] + +This adds two fields to the API for the same underlying database field +(other fields omitted for brevity): + +.. code-block:: json + + { + "published_date": "2017-04-06", + "published_date_display": "Thursday 06 April 2017" + } + +.. _Serialisers: http://www.django-rest-framework.org/api-guide/fields/ +.. _source: http://www.django-rest-framework.org/api-guide/fields/#source + +Images in the API +----------------- + +.. versionadded: 1.10 + +The :class:`~wagtail.wagtailimages.api.fields.ImageRenditionField` serialiser +allows you to add renditions of images into your API. It requires an image +filter string specifying the resize operations to perform on the image. It can +also take the ``source`` keyword argument described above. + +For example: + +.. code-block:: python + + from wagtail.wagtailimages.api.fields.ImageRenditionField + + class BlogPage(Page): + ... + + api_fields = [ + # Adds information about the source image (eg, title) into the API + APIField('feed_image'), + + # Adds a URL to a rendered thumbnail of the image to the API + APIField('feed_image_thumbnail', serializer=ImageRenditionField('fill-100x100', source='feed_image')), + ... + ] + +This would add the following to the reponse: + +.. code-block:: json + + { + "feed_image": { + "id": 45529, + "meta": { + "type": "wagtailimages.Image", + "detail_url": "http://www.example.com/api/v2/images/12/", + "tags": [] + }, + "title": "A test image", + "width": 2000, + "height": 1125 + }, + "feed_image_thumbnail": { + "url": "http://www.example.com/media/images/a_test_image.fill-100x100.jpg", + "width": 100, + "height": 100 + } + } + Additional settings ===================