Document full objects retrieval

CHANGES.rst

@@ -15,6 +15,9 @@ New Features:
 - Automatically publish docker images on hub.docker.com.
   [timo]
 
+- Add "&fullobject" parameter in @search to retrieve full objects
+  [ebrehault]
+
 Bugfixes:
 
 - Docs: Fix batching example request/response.

docs/source/searching.rst

@@ -99,3 +99,20 @@ The metadata from those columns then will be included in the results.
 In order to specify multiple columns, simply repeat the query string parameter once for every column name (the ``requests`` module will do this automatically for you if you pass it a list of values for a query string parameter).
 
 In order to retrieve all metadata columns that the catalog knows about, use ``metadata_fields=_all``.
+
+
+Retrieving full objects
+-----------------------
+
+If the data provided as metadata is not enough, you can retrieve search results as full serialized objects equivalent to what the resource GET request would produce.
+
+You do so by specifying the ``fullobjects`` parameter:
+
+.. code-block:: http
+
+    GET /plone/@search?fullobjects&SearchableText=lorem HTTP/1.1
+    Accept: application/json
+
+.. warning::
+
+    Be aware it might induces performance issues when retrieving a lot of resources. Regular search just uses lazy objects, but with full objects retrieving we wake up all the returned objects.