plone.restapi/unify-expired-and-excluded-items-handling: Merge pull request #390 from plone/docs-for-updating-locked-

Repository: plone.restapi
Branch: refs/heads/unify-expired-and-excluded-items-handling
Date: 2017-07-28T10:24:51+02:00
Author: Timo Stollenwerk (tisto) <[email protected]>
Commit: https://github.com/plone/plone.restapi/commit/e95845cb373b955f7a19a5713ce0d8952da6b03b

Merge pull request #390 from plone/docs-for-updating-locked-objects

Add documentation about updating locked objects

Files changed:
A docs/source/_json/lock_update.req
A docs/source/_json/lock_update.resp
M docs/source/locking.rst
M src/plone/restapi/tests/test_documentation.py

diff --git a/docs/source/_json/lock_update.req b/docs/source/_json/lock_update.req
new file mode 100644
index 00000000..b9e39d84
--- /dev/null
+++ b/docs/source/_json/lock_update.req
@@ -0,0 +1,9 @@
+PATCH /plone/front-page HTTP/1.1
+Accept: application/json
+Authorization: Basic YWRtaW46c2VjcmV0
+Lock-Token: 0.684672730996-0.25195226375-00105A989226:1477076400.000
+Content-Type: application/json
+
+{
+    "title": "New Title"
+}
\ No newline at end of file
diff --git a/docs/source/_json/lock_update.resp b/docs/source/_json/lock_update.resp
new file mode 100644
index 00000000..0074ded3
--- /dev/null
+++ b/docs/source/_json/lock_update.resp
@@ -0,0 +1,2 @@
+HTTP/1.1 204 No Content
+
diff --git a/docs/source/locking.rst b/docs/source/locking.rst
index 02818e2d..56097e06 100644
--- a/docs/source/locking.rst
+++ b/docs/source/locking.rst
@@ -15,7 +15,8 @@ To lock an object send a POST request to the ``/@lock`` endpoint that is availab
 ..  http:example:: curl httpie python-requests
     :request: _json/lock.req
 
-If the lock operation succeeds, the server will respond with status 200 (OK) and return various information about the lock.
+If the lock operation succeeds, the server will respond with status :term:`200 OK` and return various information
+about the lock including the lock token. The token is needed in later requests to update the locked object.
 
 .. literalinclude:: _json/lock.resp
    :language: http
@@ -32,7 +33,7 @@ The following example creates a non-stealable lock with a timeout of 1h.
     :request: _json/lock_nonstealable_timeout.req
 
 
-The server responds with status 200 (OK) and returns the lock information.
+The server responds with status :term:`200 OK` and returns the lock information.
 
 .. literalinclude:: _json/lock_nonstealable_timeout.resp
    :language: http
@@ -79,3 +80,13 @@ The server responds with status :term:`200 OK` and returns the information about
 
 .. literalinclude:: _json/lock_get.resp
    :language: http
+
+
+Updating a locked object
+------------------------
+
+To update a locked object with a PATCH request, you have to provide the lock
+token with the ``Lock-Token`` header.
+
+..  http:example:: curl httpie python-requests
+    :request: _json/lock_update.req
diff --git a/src/plone/restapi/tests/test_documentation.py b/src/plone/restapi/tests/test_documentation.py
index 2f4c7aa5..bb28114b 100644
--- a/src/plone/restapi/tests/test_documentation.py
+++ b/src/plone/restapi/tests/test_documentation.py
@@ -50,6 +50,7 @@
 REQUEST_HEADER_KEYS = [
     'accept',
     'authorization',
+    'lock-token',
 ] + TUS_HEADERS
 
 RESPONSE_HEADER_KEYS = [
@@ -1032,6 +1033,17 @@ def test_locking_lockinfo(self):
         response = self.api_session.get(url)
         save_request_and_response_for_docs('lock_get', response)
 
+    def test_update_with_lock(self):
+        url = '{}/@lock'.format(self.document.absolute_url())
+        response = self.api_session.post(url)
+        token = response.json()['token']
+        response = self.api_session.patch(
+            self.document.absolute_url(),
+            headers={'Lock-Token': token},
+            json={'title': 'New Title'})
+        response.request.headers['Lock-Token'] = u"0.684672730996-0.25195226375-00105A989226:1477076400.000"  # noqa
+        save_request_and_response_for_docs('lock_update', response)
+
 
 class TestCommenting(unittest.TestCase):
 



------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot