Merge lp:~leonardr/lazr.restful/size-link into lp:lazr.restful

[Leonard Richardson]

NOTE: this is not yet a real merge proposal because the branch is not yet ready. I'm handing the branch over to Benji, and a merge proposal is a convenient way to publicly describe the branch.

This branch makes it possible to define a named operation that returns a collection of objects, but doesn't provide a total_size. This is for cases where the total_size is expensive to calculate. In such cases, the JSON representation returned by the named operation includes a 'total_size_link' instead of a 'total_size'. A client that really wants to find out the total size can GET the total_size_link, which will invoke the operation again and _only_ return the total_size.

There are three things standing in the way of this branch being ready to land.

1. There's a test failure in django.txt.

2. There's a test for the new feature in examples/base, but there also needs to be one in webservice.txt. The test in examples/base tests operation adapters that were generated from declarations. We need a similar test in webservice.txt to test operation adapters that were defined by hand--those adapters go through a different code path.

(I'm confident that this new test will pass immediately, because I ironed out the bugs in this code path when another bug caused *all* named operations to serve total_size_link instead of total_size.)

3. Most importantly, it's not clear as a matter of policy when we should serve total_size_link instead of total_size. I implemented this branch to serve total_size_link when a named operation is annotated with @operation_returns_collection_of(..., include_total_size=False). But there's an active debate on launchpad-dev with implications for this branch. In particular, there's a good argument to be made that we should be serving total_size_link instead of total_size for *all* named operations, with the following exceptions:

 a. We should maintain the old behavior for the 'beta' and '1.0' web services.
 b. If we know that the entire list fits in one batch, we might as well serve total_size.

This question needs to be decided, and if it's decided in favor of always serving total_size_link (as IMO it should), then the annotation code needs to be removed and replaced with code that gives the old behavior up to a configurable web service version, and the new behavior afterwards.

[lp:~leonardr/lazr.restful/size-link]

139. By Leonard Richardson on 2010-07-28

Mention total_size_link in the WADL.

[Leonard Richardson (leonardr)]

While working on the lazr.restfulclient branch I realized another problem with this branch: the WADL doesn't mention total_size_link, so lazr.restfulclient can't pick it up. I changed the description of each 'page' representation to mention both 'total_size' and 'total_size_link', since there's no way of knowing which will be present for any given collection. (Not without multiplying the number of 'page' representations by two, which is stupid, or serving them dynamically, which we could do but it's not worth it.)

[lp:~leonardr/lazr.restful/size-link]

140. By Leonard Richardson on 2010-07-28

Renamed the 'number' type to the 'scalar value' type.

141. By Leonard Richardson on 2010-07-28

Link to #ScalarValue instead of now-nonexistent #Number.

=== modified file 'src/lazr/restful/_operation.py'
--- src/lazr/restful/_operation.py	2010-04-20 18:26:49 +0000
+++ src/lazr/restful/_operation.py	2010-07-28 13:24:44 +0000
@@ -12,6 +12,7 @@
 from zope.schema.interfaces import (
     IField, RequiredMissing, ValidationError, WrongType)
 from zope.security.proxy import isinstance as zope_isinstance
+from zope.traversing.browser import absoluteURL
 
 from lazr.lifecycle.event import ObjectModifiedEvent
 from lazr.lifecycle.snapshot import Snapshot
@@ -44,6 +45,23 @@
     def __init__(self, context, request):
         self.context = context
         self.request = request
+        self.total_size_only = False
+
+    def total_size_link(self, navigator):
+        """Return a link to the total size of a collection."""
+        if getattr(self, 'include_total_size', True):
+            # This is a named operation that includes the total size
+            # inline rather than with a link.
+            return None
+        if not IResourceGETOperation.providedBy(self):
+            # Only GET operations can have their total size split out into
+            # a link, because only GET operations are safe.
+            return None
+        base = str(self.request.URL)
+        query = navigator.getCleanQueryString()
+        if query != '':
+            query += '&'
+        return base + '?' + query + "ws.show=total_size"
 
     def __call__(self):
         values, errors = self.validate()
@@ -84,9 +102,14 @@
             # If the result is a web service collection, serve only one
             # batch of the collection.
             collection = getMultiAdapter((result, self.request), ICollection)
-            result = CollectionResource(collection, self.request).batch() + '}'
+            resource = CollectionResource(collection, self.request)
+            result = resource.batch(total_size_only=self.total_size_only)
+            if not self.total_size_only:
+                result += '}'
         elif self.should_batch(result):
-            result = self.batch(result, self.request) + '}'
+            result = self.batch(result, self.request, self.total_size_only)
+            if not self.total_size_only:
+                result += '}'
         else:
             # Serialize the result to JSON. Any embedded entries will be
             # automatically serialized.

=== modified file 'src/lazr/restful/_resource.py'
--- src/lazr/restful/_resource.py	2010-06-14 15:24:20 +0000
+++ src/lazr/restful/_resource.py	2010-07-28 13:24:44 +0000
@@ -597,19 +597,34 @@
         # super() even though this class itself has no superclass.
         super(BatchingResourceMixin, self).__init__(context, request)
 
-    def batch(self, entries, request):
+    def total_size_link(self, navigator):
+        """Return the URL to fetch to find out the collection's total size.
+
+        If this is None, the total size will be included inline.
+
+        :param navigator: A BatchNavigator object for the current batch.
+        """
+        return None
+
+    def batch(self, entries, request, total_size_only=False):
         """Prepare a batch from a (possibly huge) list of entries.
 
-        :return: A JSON string representing a hash:
+        :return: If size_only is True, a JSON string
+        representing the number of objects in the list as a whole. If
+        size_only is False, a JSON string representing a hash:
+
         'entries' contains a list of EntryResource objects for the
           entries that actually made it into this batch
         'total_size' contains the total size of the list.
+        'total_size_link' contains a link to the total size of the list.
         'next_url', if present, contains a URL to get the next batch
          in the list.
         'prev_url', if present, contains a URL to get the previous batch
          in the list.
         'start' contains the starting index of this batch
 
+        Only one of 'total_size' or 'total_size_link' will be present.
+
         Note that the JSON string will be missing its final curly
         brace. This is in case the caller wants to add some additional
         keys to the JSON hash. It's the caller's responsibility to add
@@ -619,12 +634,19 @@
             entries = IFiniteSequence(entries)
         navigator = WebServiceBatchNavigator(entries, request)
 
+        if total_size_only:
+            return simplejson.dumps(navigator.batch.listlength)
+
         view_permission = getUtility(IWebServiceConfiguration).view_permission
         resources = [EntryResource(entry, request)
                      for entry in navigator.batch
                      if checkPermission(view_permission, entry)]
-        batch = { 'total_size' : navigator.batch.listlength,
-                  'start' : navigator.batch.start }
+        batch = { 'start' : navigator.batch.start }
+        total_size_link = self.total_size_link(navigator)
+        if total_size_link is None:
+            batch['total_size'] = navigator.batch.listlength
+        else:
+            batch['total_size_link'] = total_size_link
         if navigator.batch.start < 0:
             batch['start'] = None
         next_url = navigator.nextBatchURL()
@@ -674,6 +696,10 @@
         except ComponentLookupError:
             self.request.response.setStatus(400)
             return "No such operation: " + operation_name
+
+        show = self.request.form.get('ws.show')
+        if show == 'total_size':
+            operation.total_size_only = True
         return operation()
 
     def handleCustomPOST(self, operation_name):
@@ -1663,14 +1689,15 @@
         self.request.response.setHeader('Content-type', self.JSON_TYPE)
         return result
 
-    def batch(self, entries=None):
+    def batch(self, entries=None, total_size_only=False):
         """Return a JSON representation of a batch of entries.
 
         :param entries: (Optional) A precomputed list of entries to batch.
         """
         if entries is None:
             entries = self.collection.find()
-        result = super(CollectionResource, self).batch(entries, self.request)
+        result = super(CollectionResource, self).batch(
+            entries, self.request, total_size_only)
         result += (
             ', "resource_type_link" : ' + simplejson.dumps(self.type_url)
             + '}')

=== modified file 'src/lazr/restful/declarations.py'
--- src/lazr/restful/declarations.py	2010-05-07 14:02:44 +0000
+++ src/lazr/restful/declarations.py	2010-07-28 13:24:44 +0000
@@ -707,20 +707,24 @@
 class operation_returns_collection_of(_method_annotator):
     """Specify that the exported operation returns a collection.
 
-    The decorator takes a single argument: an interface that's been
-    exported as an entry.
+    The decorator takes one required argument, "schema", an interface
+    that's been exported as an entry. It takes one optional argument,
+    "include_total_size", which controls whether the total size of the
+    resultset is included inline, or whether the client has to follow
+    a link to find it (because it's very expensive to calculate).
     """
-
-    def __init__(self, schema):
+    def __init__(self, schema, include_total_size=True):
         _check_called_from_interface_def('%s()' % self.__class__.__name__)
         if not IInterface.providedBy(schema):
             raise TypeError('Collection value type %s does not provide '
                             'IInterface.' % schema)
         self.return_type = CollectionField(
             value_type=Reference(schema=schema))
+        self.include_total_size = include_total_size
 
     def annotate_method(self, method, annotations):
         annotations['return_type'] = self.return_type
+        annotations['include_total_size'] = self.include_total_size
 
 
 class _export_operation(_method_annotator):
@@ -1173,23 +1177,22 @@
         version = getUtility(IWebServiceConfiguration).active_versions[0]
 
     bases = (BaseResourceOperationAdapter, )
-    if tag['type'] == 'read_operation':
+    operation_type = tag['type']
+    if operation_type == 'read_operation':
         prefix = 'GET'
         provides = IResourceGETOperation
-    elif tag['type'] in ('factory', 'write_operation'):
+    elif operation_type in ('factory', 'write_operation'):
         provides = IResourcePOSTOperation
         prefix = 'POST'
-        if tag['type'] == 'factory':
+        if operation_type == 'factory':
             bases = (BaseFactoryResourceOperationAdapter,)
-    elif tag['type'] == 'destructor':
+    elif operation_type == 'destructor':
         provides = IResourceDELETEOperation
         prefix = 'DELETE'
     else:
-        raise AssertionError('Unknown method export type: %s' % tag['type'])
+        raise AssertionError('Unknown method export type: %s' % operation_type)
 
     return_type = tag['return_type']
-    if return_type is None:
-        return_type = None
 
     name = _versioned_class_name(
         '%s_%s_%s' % (prefix, method.interface.__name__, tag['as']),
@@ -1200,7 +1203,15 @@
              '_method_name': method.__name__,
              '__doc__': method.__doc__}
 
-    if tag['type'] == 'write_operation':
+    if isinstance(return_type, CollectionField):
+        include_total_size = tag.get('include_total_size', True)
+        if not include_total_size and operation_type != 'read_operation':
+            raise AssertionError(
+                "Only read operations can decline to set "
+                "include_total_size.")
+        class_dict['include_total_size'] = include_total_size
+
+    if operation_type == 'write_operation':
         class_dict['send_modification_event'] = True
     factory = type(name, bases, class_dict)
     classImplements(factory, provides)

=== modified file 'src/lazr/restful/docs/webservice-declarations.txt'
--- src/lazr/restful/docs/webservice-declarations.txt	2010-05-07 15:32:27 +0000
+++ src/lazr/restful/docs/webservice-declarations.txt	2010-07-28 13:24:44 +0000
@@ -32,7 +32,7 @@
 field, but not the inventory_number field.
 
     >>> from zope.interface import Interface
-    >>> from zope.schema import TextLine, Float
+    >>> from zope.schema import Text, TextLine, Float
     >>> from lazr.restful.declarations import (
     ...     export_as_webservice_entry, exported)
     >>> class IBook(Interface):
@@ -48,6 +48,8 @@
     ...         exported_as='price')
     ...
     ...     inventory_number = TextLine(title=u'The inventory part number.')
+    ...
+    ...     text = exported(Text(title=u'The text of the book'))
 
 These declarations add tagged values to the original interface elements.
 The tags are in the lazr.restful namespace and are dictionaries of
@@ -212,7 +214,7 @@
     TypeError: export_as_webservice_collection() is missing a method
     tagged with @collection_default_content.
 
-As it is an error, to mark more than one methods:
+As it is an error, to mark more than one method:
 
     >>> class TwoDefaultContent(Interface):
     ...     export_as_webservice_collection(IDummyInterface)
@@ -329,8 +331,15 @@
     ...         text=copy_field(IBook['title'], title=u'Text to search for.'))
     ...     @operation_returns_collection_of(IBook)
     ...     @export_read_operation()
-    ...     def searchBooks(text):
-    ...         """Return list of books containing 'text'."""
+    ...     def searchBookTitles(text):
+    ...         """Return list of books whose titles contain 'text'."""
+    ...
+    ...     @operation_parameters(
+    ...         text=copy_field(IBook['text'], title=u'Text to search for.'))
+    ...     @operation_returns_collection_of(IBook, include_total_size=False)
+    ...     @export_read_operation()
+    ...     def searchBookText(text):
+    ...         """Return list of books whose text contains 'text'."""
     ...
     ...     @operation_parameters(
     ...         text=copy_field(IBook['title'], title=u'Text to search for.'))
@@ -392,16 +401,32 @@
     return_type: <lazr.restful._operation.ObjectLink object...>
     type: 'factory'
 
-We did specify the return type for the 'searchBooks' method: it
-returns a collection.
+We did specify the return type for the 'searchBookTitles' method: it
+returns a collection. Searching the titles of books is cheap, so when
+lazr.restful serves a page of results, it can include the total size
+of the collection.
 
-    >>> print_export_tag(IBookSetOnSteroids['searchBooks'])
-    as: 'searchBooks'
+    >>> print_export_tag(IBookSetOnSteroids['searchBookTitles'])
+    as: 'searchBookTitles'
     call_with: {}
+    include_total_size: True
     params: {'text': <...TextLine...>}
     return_type: <lazr.restful.fields.CollectionField object...>
     type: 'read_operation'
 
+The 'searchBookText' method returns the same kind of
+collection. Searching the full text of books is quite expensive, so
+when lazr.restful searches a page of results, we've told it not to
+include the total size of the collection.
+
+    >>> print_export_tag(IBookSetOnSteroids['searchBookText'])
+    as: 'searchBookText'
+    call_with: {}
+    include_total_size: False
+    params: {'text': <...Text...>}
+    return_type: <lazr.restful.fields.CollectionField object...>
+    type: 'read_operation'
+
 The 'bestMatch' method returns an entry.
 
     >>> print_export_tag(IBookSetOnSteroids['bestMatch'])
@@ -817,6 +842,7 @@
     >>> dump_entry_interface(entry_interface)
     author: TextLine
     price: Float
+    text: Text
     title: TextLine
 
 The field __name__ attribute contains the exported name:
@@ -888,9 +914,11 @@
     >>> class Book(object):
     ...     """Simple IBook implementation."""
     ...     implements(IBook)
-    ...     def __init__(self, author, title, base_price, inventory_number):
+    ...     def __init__(self, author, title, text, base_price,
+    ...                  inventory_number):
     ...         self.author = author
     ...         self.title = title
+    ...         self.text = text
     ...         self.base_price = base_price
     ...         self.inventory_number = inventory_number
 
@@ -942,7 +970,7 @@
 IBookEntry.
 
     >>> entry_adapter = entry_adapter_factory(
-    ...     Book(u'Aldous Huxley', u'Island', 10.0, '12345'),
+    ...     Book(u'Aldous Huxley', u'Island', 'Text here', 10.0, '12345'),
     ...     request)
 
     >>> entry_adapter.schema is entry_interface
@@ -1058,7 +1086,7 @@
     ...     generate_operation_adapter)
 
     >>> read_method_adapter_factory = generate_operation_adapter(
-    ...     IBookSetOnSteroids['searchBooks'])
+    ...     IBookSetOnSteroids['searchBookTitles'])
     >>> IResourceGETOperation.implementedBy(read_method_adapter_factory)
     True
 
@@ -1070,14 +1098,14 @@
 
     >>> from lazr.restful import ResourceOperation
     >>> read_method_adapter_factory.__name__
-    'GET_IBookSetOnSteroids_searchBooks_beta'
+    'GET_IBookSetOnSteroids_searchBookTitles_beta'
     >>> issubclass(read_method_adapter_factory, ResourceOperation)
     True
 
 The adapter's docstring is taken from the decorated method docstring.
 
     >>> read_method_adapter_factory.__doc__
-    "Return list of books containing 'text'."
+    "Return list of books whose titles contain 'text'."
 
 The adapter's params attribute contains the specification of the
 parameters accepted by the operation.
@@ -1097,11 +1125,15 @@
     ...
     ...     result = None
     ...
-    ...     def searchBooks(self, text):
+    ...     def searchBookTitles(self, text):
+    ...         return self.result
+    ...
+    ...     def searchBookText(self, text):
     ...         return self.result
     ...
     ...     def new(self, author, base_price, title):
-    ...         return Book(author, title, base_price, "unknown")
+    ...         return Book(author, title, "default text", base_price,
+    ...                     "unknown")
 
 Now we can create a fake request that invokes the named operation.
 
@@ -1148,7 +1180,8 @@
 
     >>> write_method_adapter = write_method_adapter_factory(
     ...     BookOnSteroids(
-    ...         'Aldous Huxley', 'The Doors of Perception', 8, 'unknown'),
+    ...         'Aldous Huxley', 'The Doors of Perception',
+    ...         'The text', 8, 'unknown'),
     ...     FakeRequest())
 
     >>> verifyObject(IResourcePOSTOperation, write_method_adapter)
@@ -2447,8 +2480,8 @@
     # ProxyFactory wraps the content using the defined checker.
     >>> print debug_proxy(ProxyFactory(entry_adapter))
     zope.security._proxy._Proxy (using zope.security.checker.Checker)
-        public: author, price, schema, title
-        public (set): author, price, schema, title
+        public: author, price, schema, text, title
+        public (set): author, price, schema, text, title
 
     >>> print debug_proxy(ProxyFactory(collection_adapter))
     zope.security._proxy._Proxy (using zope.security.checker.Checker)
@@ -2511,7 +2544,8 @@
 ICollection are available:
 
     >>> from zope.component import getMultiAdapter
-    >>> book = Book(u'George Orwell', u'1984', 10.0, u'12345-1984')
+    >>> book = Book(u'George Orwell', u'1984', 'Text here', 10.0,
+    ...             u'12345-1984')
     >>> bookset = BookSet([book])
 
     >>> entry_adapter = getMultiAdapter((book, request), IEntry)
@@ -2537,8 +2571,12 @@
     >>> request_interface = IWebServiceClientRequest
     >>> adapter_registry.lookup(
     ...     (IBookSetOnSteroids, request_interface),
-    ...     IResourceGETOperation, 'searchBooks')
-    <class '...GET_IBookSetOnSteroids_searchBooks_beta'>
+    ...     IResourceGETOperation, 'searchBookTitles')
+    <class '...GET_IBookSetOnSteroids_searchBookTitles_beta'>
+    >>> adapter_registry.lookup(
+    ...     (IBookSetOnSteroids, request_interface),
+    ...     IResourceGETOperation, 'searchBookText')
+    <class '...GET_IBookSetOnSteroids_searchBookText_beta'>
     >>> adapter_registry.lookup(
     ...     (IBookSetOnSteroids, request_interface),
     ...     IResourcePOSTOperation, 'create_book')
@@ -2619,6 +2657,25 @@
     that version. The bad annotations are: "params", "as".
     ...
 
+Here's a class that tries to define a write operation that returns a
+collection without including the total size of the collection.
+lazr.restful prohibits this: write operations are unsafe, and whatever
+collection a write operation might return, retrieving its size in a
+separate request would mean changing the dataset twice.
+
+    >>> class IWriteOperationWithoutTotalSize(Interface):
+    ...     export_as_webservice_entry()
+    ...     @operation_returns_collection_of(IBook, include_total_size=False)
+    ...     @export_write_operation()
+    ...     def a_method(**kwargs): pass
+    >>> register_test_module('badwrite', IWriteOperationWithoutTotalSize)
+    Traceback (most recent call last):
+    ...
+    ConfigurationExecutionError: ... Only read operations can decline
+    to set include_total_size.
+    ...
+
+
 Mutators as named operations
 ----------------------------
 

=== modified file 'src/lazr/restful/example/base/interfaces.py'
--- src/lazr/restful/example/base/interfaces.py	2010-02-15 14:53:11 +0000
+++ src/lazr/restful/example/base/interfaces.py	2010-07-28 13:24:44 +0000
@@ -188,7 +188,7 @@
         search=TextLine(title=u"String to search for in recipe name."),
         vegetarian=Bool(title=u"Whether or not to limit the search to "
                         "vegetarian cookbooks.", default=False))
-    @operation_returns_collection_of(IRecipe)
+    @operation_returns_collection_of(IRecipe, include_total_size=False)
     @export_read_operation()
     def find_recipes(search, vegetarian):
         """Search for recipes across cookbooks."""

=== modified file 'src/lazr/restful/example/base/tests/collection.txt'
--- src/lazr/restful/example/base/tests/collection.txt	2009-04-24 15:14:07 +0000
+++ src/lazr/restful/example/base/tests/collection.txt	2010-07-28 13:24:44 +0000
@@ -173,14 +173,12 @@
     ...         "/cookbooks?ws.op=find_recipes&%s" % args).jsonBody()
 
     >>> s_recipes = search_recipes("chicken")
-    >>> s_recipes['total_size']
-    3
     >>> sorted(r['instructions'] for r in s_recipes['entries'])
     [u'Draw, singe, stuff, and truss...', u'You can always judge...']
 
     >>> veg_recipes = search_recipes("chicken", True)
-    >>> veg_recipes['total_size']
-    0
+    >>> veg_recipes['entries']
+    []
 
 A custom operation that returns a list of objects is paginated, just
 like a collection.
@@ -196,11 +194,22 @@
 empty list of results:
 
     >>> empty_collection = search_recipes("nosuchrecipe")
-    >>> empty_collection['total_size']
-    0
     >>> [r['instructions'] for r in empty_collection['entries']]
     []
 
+Some named operations that return a collection include the total size
+of the collection inline. The 'search_recipes' operation includes a
+_link_ to the total size of the collection.
+
+   >>> print s_recipes['total_size_link']
+   http://.../cookbooks?search=chicken&vegetarian=false&ws.op=find_recipes&ws.show=total_size
+
+Sending a GET request to that link yields a JSON representation of the
+total size.
+
+   >>> print webservice.get(s_recipes['total_size_link']).jsonBody()
+   3
+
 Custom operations may have error handling. In this case, the error
 handling is in the validate() method of the 'search' field.
 
@@ -216,9 +225,11 @@
 
     >>> general_cookbooks = webservice.get(
     ...     "/cookbooks?ws.op=find_for_cuisine&cuisine=General")
-    >>> general_cookbooks.jsonBody()['total_size']
+    >>> print general_cookbooks.jsonBody()['total_size']
     3
 
+
+
 POST operations
 ===============
 

=== modified file 'src/lazr/restful/example/base/tests/wadl.txt'
--- src/lazr/restful/example/base/tests/wadl.txt	2010-03-10 18:45:04 +0000
+++ src/lazr/restful/example/base/tests/wadl.txt	2010-07-28 13:24:44 +0000
@@ -537,8 +537,9 @@
 'entry_resource_descriptions'.
 
     >>> entry_resource_descriptions = []
-    >>> entry_resource_types = other_children[first_entry_type_index:-2]
-    >>> hosted_binary_resource_type, simple_binary_type = other_children[-2:]
+    >>> entry_resource_types = other_children[first_entry_type_index:-3]
+    >>> (hosted_binary_resource_type, scalar_type, simple_binary_type
+    ...     ) = other_children[-3:]
     >>> for index in range(0, len(entry_resource_types), 5):
     ...     entry_resource_descriptions.append(
     ...         (tuple(entry_resource_types[index:index + 5])))
@@ -1155,9 +1156,9 @@
 All collection representations have the same five <param> tags.
 
     >>> [param.attrib['name'] for param in collection_rep]
-    ['resource_type_link', 'total_size', 'start', 'next_collection_link',
-     'prev_collection_link', 'entries', 'entry_links']
-    >>> (type_link, size, start, next, prev, entries,
+    ['resource_type_link', 'total_size', 'total_size_link', 'start',
+     'next_collection_link', 'prev_collection_link', 'entries', 'entry_links']
+    >>> (type_link, size, size_link, start, next, prev, entries,
     ...  entry_links) = collection_rep
 
 So what's the difference between a collection of people and a

=== modified file 'src/lazr/restful/templates/wadl-root.pt'
--- src/lazr/restful/templates/wadl-root.pt	2010-03-10 18:50:27 +0000
+++ src/lazr/restful/templates/wadl-root.pt	2010-07-28 13:24:44 +0000
@@ -292,7 +292,12 @@
       </param>
 
       <param style="plain" name="total_size" path="$['total_size']"
-             required="true" />
+             required="false" />
+
+      <param style="plain" name="total_size_link" path="$['total_size_link']"
+             required="false">
+        <link resource_type="#ScalarValue" />
+      </param>
 
       <param style="plain" name="start" path="$['start']" required="true" />
 
@@ -321,7 +326,7 @@
   <!--End representation and resource_type definitions for entry
       resources. -->
 
-  <!--Finally, describe the 'hosted binary file' type.-->
+  <!--Finally, describe the 'hosted binary file' type...-->
   <resource_type id="HostedFile">
     <method name="GET" id="HostedFile-get">
       <response>
@@ -334,6 +339,15 @@
     <method name="DELETE" id="HostedFile-delete" />
   </resource_type>
 
+  <!--...and the simple 'scalar value' type.-->
+  <resource_type id="ScalarValue">
+   <method name="GET" id="ScalarValue-get">
+    <response>
+     <representation mediaType="application/json" />
+    </response>
+   </method>
+  </resource_type>
+
   <!--Define a data type for binary data.-->
   <xsd:simpleType name="binary">
    <xsd:list itemType="byte" />