Document Versioning

docs/config.rst

@@ -361,6 +361,35 @@ uppercase.
                                 otherwise. See :ref:`jsonxml`. Defaults to 
                                 ``True``.
 
+``VERSIONING``                  Enabled documents version control when``True``. Can be erridden by resource settings. Defaults to ``False``.
+
+``VERSIONS``                    Suffix added to the name of the primary
+                                collection to create the name of the shadow
+                                collection to store document versions. Defaults
+                                to ``_versions``. When ``VERSIONING`` is enabled
+                                , a collection such as ``myresource_versions``
+                                would be created for a resource with a
+                                datasource of ``myresource``.
+
+``VERSION_PARAM``               The URL query parameter used to access the
+                                specific version of a document. Defaults to
+                                ``version``. Omit this parameter to get the
+                                latest version of a document or use 
+                                `?version=all`` to get a list of all version of
+                                the document. Only valid for individual item
+                                endpoints.
+
+``VERSION``                     Field used to store the version number of a
+                                document. Defaults to ``_version``.
+
+``LASTEST_VERSION``             Field used to store the latest version number
+                                of a document. Defaults to ``_latest_version``.
+
+``VERSION_ID_SUFFIX``           Used in the shadow collection to store the
+                                document id. Defaults to ``_document``. If
+                                ``ID_FIELD`` is set to ``_id``, the document id
+                                will be stored in field ``_id_document``.
+
 ``MONGO_HOST``                  MongoDB server address. Defaults to ``localhost``.
 
 ``MONGO_PORT``                  MongoDB port. Defaults to ``27017``.
@@ -774,13 +803,18 @@ defining the field validation rules. Allowed validation rules are:
                                 - ``resource``: the name of the resource being referenced;
                                 - ``field``: the field name in the foreign resource;
                                 - ``embeddable``: set to ``True`` if clients can request the referenced document to be embedded with the serialization. See :ref:`embedded_docs`. Defaults to ``False``.
+                                - ``version``: set to ``True`` to require a ``_version`` with the data relation. See :ref:`document_versioning`. Defaults to ``False``.
 
-``nullable``                    If ``True`` the field value can be set to 
+``nullable``                    If ``True``, the field value can be set to 
                                 ``None``. 
 
 ``default``                     The default value for the field. When serving
                                 POST (create) requests, missing fields will be
                                 assigned the configured default values.
+
+``versioned``                   If ``True``, this field will be included in the
+                                versioned history of each document when
+                                ``versioning`` is enabled. Defaults to ``True``.
 =============================== ==============================================
 
 Schema syntax is based on Cerberus_ and yes, it can be extended.  In fact, Eve

docs/features.rst

@@ -630,7 +630,7 @@ validation class to validate that. Or say you want to make sure that a VAT
 field actually matches your own country VAT algorithm; you can do that too. As
 a matter of fact, Eve's MongoDB data-layer itself extends Cerberus
 validation by implementing the ``unique`` schema field constraint. For more
-information see :ref:`validation`
+information see :ref:`validation`.
 
 .. _cache_control:
 
@@ -653,15 +653,44 @@ The response above includes both ``Cache-Control`` and ``Expires`` headers.
 These will minimize load on the server since cache-enabled consumers will
 perform resource-intensive request only when really needed.
 
-Versioning
-----------
+API Versioning
+--------------
 I'm not too fond of API versioning. I believe that clients should be
 intelligent enough to deal with API updates transparently, especially since
 Eve-powered API support HATEOAS_. When versioning is a necessity, different API
 versions should be isolated instances since so many things could be different
 between versions: caching, URIs, schemas, validation, and so on. URI versioning
 (http://api.example.com/v1/...) is supported.
 
+.. _document_versioning:
+
+Document Versioning
+-------------------
+Eve supports automatic version control of documents. By default, this setting is
+turned off, but it can be turned globally or configured individually for each
+resource. When enabled, Eve provides version control by storing versions of
+documents in a shadow collection. All HTTP methods act on the latest version of 
+the document except when retrieving an indivual item. In this case, adding a
+query parameter of ``?version=VERSION`` can be used to point to a specific
+version. Special values of  ``?version=all`` and  ``?version=diffs`` are also
+valid. (Bonus tip - try a projection on top of ``?version=all``!) Additional
+fields called ``_version`` and ``_latest_version`` get automatically added to
+documents when versioning is turned on.
+
+It is important to note that there are a few non-standard scenarios which could
+produce unexpected results when versioning is turned on. In particular, document
+history will not be saved when modifying collections outside of the Eve
+generated API. Also, if at anytime the ``VERSION`` field gets removed from the
+primary document (which cannot happen through the API when versioning is turned
+on), a subsequent write will re-initialize the ``VERSION`` number with
+``VERSION`` = 1. At this time there will be multiple versions of the document
+with the same version number. In normal practice, ``VERSIONING`` can be enable
+without worry for any new collection or even an existing collection which has
+not previously had versioning enabled.
+
+For more information see and `Global Configuration`_ and `Domain Configuration`_.
+
+
 Authentication
 --------------
 Customizable Basic Authentication (RFC-2617), Token-based authentication and
@@ -775,6 +804,42 @@ toggling the ``embedding`` value). Furthermore, only fields with the
 ``embeddable`` value explicitly set to ``True`` will allow the embedding of
 referenced documents.
 
+Embedding also works with a data_relation to a specific version of a document,
+but the schema looks a little bit different. To enable the data_relation to a
+specific version, add ``'version': True`` to the data_relation block. You'll
+also want to change the ``type`` to ``dict`` and add the ``schema`` definition
+shown below.
+
+.. code-block:: python
+   :emphasize-lines: 5, 6, 11
+
+    DOMAIN = {
+        'emails': {
+            'schema': {
+                'author': {
+                    'type': 'dict',
+                    'schema': {
+                        '_id': {'type': 'objectid'},
+                        '_version': {'type': 'integer'}
+                    },
+                    'data_relation': {
+                        'resource': 'users',
+                        'field': '_id',
+                        'embeddable': True,
+                        'version': True,
+                    },
+                },
+                'subject': {'type': 'string'},
+                'body': {'type': 'string'},
+            }
+        }
+
+As you can see, ``'version': True`` changes the expected value of a
+data_relation field to a dictionary with fields names ``data_relation['field']``
+and ``VERSION``. With ``'field': '_id'`` in the data_relation definition above
+and ``VERSION = '_version'`` in the Eve config, the value of the data_relation
+in this scenario would be a dictionary with fields ``_id`` and ``_version``.
+
 Predefined Resource Serialization
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 It is also possible to elect some fields for predefined resource

eve/__init__.py

@@ -55,6 +55,7 @@
 ITEMS = '_items'
 LINKS = '_links'
 ETAG = '_etag'
+VERSION = '_version'
 
 # must be the last line (will raise W402 on pyflakes)
 from eve.flaskapp import Eve  # noqa

eve/default_settings.py

@@ -13,6 +13,13 @@
 
     .. versionchanged:: 0.4
        URL_PROTOCOL added and set to ''.
+       'VERSION' added and set to '_version'.
+       'VERSIONS' added and set to '_versions'.
+       'VERSIONING' added and set to False.
+       'VERSION_PARAM' added and set to 'version'.
+       'LATEST_VERSION' added and set to '_latest_version'.
+       'VERSION_ID_SUFFIX' added and set to '_document'.
+       'VERSION_DIFF_INCLUDE' added and set to [].
 
     .. versionchanged:: 0.3
        X_MAX_AGE added and set to 21600.
@@ -64,6 +71,13 @@
 ITEMS = '_items'
 LINKS = '_links'
 ETAG = '_etag'
+VERSION = '_version'            # field that stores the version number
+LATEST_VERSION = '_latest_version'  # field returned on GET requests so we know
+                                # if we have the latest copy even if we access
+                                # a specific version
+VERSION_ID_SUFFIX = '_document'  # appended to ID_FIELD, holds the original
+                                # document id in parallel collection
+VERSION_DIFF_INCLUDE = []       # always include these fields when diffing
 
 API_VERSION = ''
 URL_PREFIX = ''
@@ -87,6 +101,9 @@
 PAGINATION = True               # pagination enabled by default.
 PAGINATION_LIMIT = 50
 PAGINATION_DEFAULT = 25
+VERSIONING = False              # turn document versioning on or off
+VERSIONS = '_versions'          # suffix for parallel collection w/old versions
+VERSION_PARAM = 'version'       # URL param for specific version of a document
 
 RESOURCE_METHODS = ['GET']
 ITEM_METHODS = ['GET']
@@ -100,7 +117,7 @@
 
 # list of extra fields to be included with every POST response. This list
 # should not include the 'standard' fields (ID_FIELD, LAST_UPDATED,
-# DATE_CREATED,ETAG).
+# DATE_CREATED, and ETAG).
 EXTRA_RESPONSE_FIELDS = []
 
 

eve/endpoints.py

@@ -107,6 +107,9 @@ def item_endpoint(**lookup):
 def home_endpoint():
     """ Home/API entry point. Will provide links to each available resource
 
+    .. versionchanged:: 0.4
+       Prevent versioning collections from being added in links.
+
     .. versionchanged:: 0.2
        Use new 'resource_title' setting for link titles.
 
@@ -117,9 +120,10 @@ def home_endpoint():
         response = {}
         links = []
         for resource in config.DOMAIN.keys():
-            links.append({'href': '%s' % resource_uri(resource),
-                          'title': '%s' %
-                          config.DOMAIN[resource]['resource_title']})
+            if not resource.endswith(config.VERSIONS):
+                links.append({'href': '%s' % resource_uri(resource),
+                              'title': '%s' %
+                              config.DOMAIN[resource]['resource_title']})
         response[config.LINKS] = {'child': links}
         return send_response(None, (response,))
     else: