plone.restapi/plone-only-login: Add docs for expansion.

Repository: plone.restapi
Branch: refs/heads/plone-only-login
Date: 2017-07-25T11:48:31+02:00
Author: Timo Stollenwerk (tisto) <[email protected]>
Commit: https://github.com/plone/plone.restapi/commit/9a03d92dc233d6a39c8be2d8d3deb47254ee46b3

Add docs for expansion.

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

diff --git a/docs/source/_json/expansion.req b/docs/source/_json/expansion.req
new file mode 100644
index 00000000..f9df6e4c
--- /dev/null
+++ b/docs/source/_json/expansion.req
@@ -0,0 +1,3 @@
+GET /plone/front-page?expand=breadcrumbs,workflow HTTP/1.1
+Accept: application/json
+Authorization: Basic YWRtaW46c2VjcmV0
diff --git a/docs/source/_json/expansion.resp b/docs/source/_json/expansion.resp
new file mode 100644
index 00000000..69711721
--- /dev/null
+++ b/docs/source/_json/expansion.resp
@@ -0,0 +1,79 @@
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "@components": {
+    "breadcrumbs": [
+      {
+        "title": "Welcome to Plone", 
+        "url": "http://localhost:55001/plone/front-page"
+      }
+    ], 
+    "navigation": {
+      "@id": "http://localhost:55001/plone/front-page/@components/navigation"
+    }
+  }, 
+  "@id": "http://localhost:55001/plone/front-page", 
+  "@type": "Document", 
+  "@workflow": {
+    "history": [
+      {
+        "action": null, 
+        "actor": "test_user_1_", 
+        "comments": "", 
+        "review_state": "private", 
+        "time": "2016-10-21T19:00:00+00:00", 
+        "title": "Private"
+      }
+    ], 
+    "transitions": [
+      {
+        "@id": "http://localhost:55001/plone/front-page/@workflow/publish", 
+        "title": "Publish"
+      }, 
+      {
+        "@id": "http://localhost:55001/plone/front-page/@workflow/submit", 
+        "title": "Submit for publication"
+      }
+    ]
+  }, 
+  "UID": "24f0d86c37ee4ebc889baa39bab56b20", 
+  "allow_discussion": true, 
+  "changeNote": "", 
+  "contributors": [], 
+  "created": "2016-01-21T01:14:48+00:00", 
+  "creators": [
+    "test_user_1_", 
+    "admin"
+  ], 
+  "description": "Congratulations! You have successfully installed Plone.", 
+  "effective": null, 
+  "exclude_from_nav": false, 
+  "expires": null, 
+  "id": "front-page", 
+  "language": "", 
+  "layout": "document_view", 
+  "modified": "2016-01-21T01:24:11+00:00", 
+  "parent": {
+    "@id": "http://localhost:55001/plone", 
+    "@type": "Plone Site", 
+    "description": "", 
+    "title": "Plone site"
+  }, 
+  "relatedItems": [], 
+  "review_state": "private", 
+  "rights": "", 
+  "sharing": {
+    "@id": "http://localhost:55001/plone/front-page/@sharing", 
+    "title": "Sharing"
+  }, 
+  "subjects": [], 
+  "table_of_contents": null, 
+  "text": {
+    "content-type": "text/plain", 
+    "data": "<p>If you're seeing this instead of the web site you were expecting, the owner of this web site has just installed Plone. Do not contact the Plone Team or the Plone mailing lists about this.</p>", 
+    "encoding": "utf-8"
+  }, 
+  "title": "Welcome to Plone", 
+  "version": "current"
+}
\ No newline at end of file
diff --git a/docs/source/expansion.rst b/docs/source/expansion.rst
new file mode 100644
index 00000000..b93e850a
--- /dev/null
+++ b/docs/source/expansion.rst
@@ -0,0 +1,113 @@
+Expansion
+=========
+
+Expansion is a mechanism in plone.restapi to embed additional "components", 
+such as navigation, breadcrumbs, schema, or workflow within the main content 
+response. This helps the API consumers to avoid unneccesary request.
+
+Say you want to show a document in Plone together with the breadcrumbs and a
+workflow switcher. Instead of doing three individual requests, you can just 
+expand the breadcrumbs and the workflow "components".
+
+The list of expandable components is listed in the "@components" attribute 
+in the reponse of any content GET request::
+
+  GET /plone/front-page HTTP/1.1
+  Accept: application/json
+  Authorization: Basic YWRtaW46c2VjcmV0
+
+  {
+    "@id": "http://localhost:55001/plone/front-page",
+    "@type": "Document",
+    "@components": {
+      "breadcrumbs": "http://localhost:55001/plone/front-page/@breadcrumbs",
+      "navigation": "http://localhost:55001/plone/front-page/@navigation",
+      "schema": "http://localhost:55001/plone/front-page/@schema",
+      "workflow": "http://localhost:55001/plone/front-page/@workflow"
+    },
+    "UID": "1f699ffa110e45afb1ba502f75f7ec33",
+    "title": "Welcome to Plone",
+    ...
+  }
+
+Alternative::
+
+  {
+    "@id": "http://localhost:55001/plone/front-page",
+    "@type": "Document",
+    "@components": [
+        {"@id": "http://localhost:55001/plone/front-page/@breadcrumbs"},
+        {"@id": "http://localhost:55001/plone/front-page/@navigation"},
+        {"@id": "http://localhost:55001/plone/front-page/@schema"},
+        {"@id": "http://localhost:55001/plone/front-page/@workflow"}
+    },
+    "UID": "1f699ffa110e45afb1ba502f75f7ec33",
+    "title": "Welcome to Plone",
+    ...
+  }
+
+(pro: same structure as expanded, con: hard to differentiate from expanded version)
+
+In order to expand and embed one or more components, use the "expand" GET 
+parameter and provide either a single component or a comma-separated list
+of the components you want to embed. Say you want to expand the "breadcrumbs"
+and the "workflow" components::
+
+  GET /plone/front-page?expand=breadcrumbs,workflow HTTP/1.1
+  Accept: application/json
+  Authorization: Basic YWRtaW46c2VjcmV0
+
+  {
+    "@id": "http://localhost:55001/plone/front-page",
+    "@type": "Document",
+    "@components": {
+      "breadcrumbs": {
+        "@id": "http://localhost:55001/plone/front-page/@components/breadcrumbs", 
+        "items": [
+          {
+            "title": "Welcome to Plone", 
+            "url": "http://localhost:55001/plone/front-page"
+          }
+        ]
+      },
+      "navigation": "http://localhost:55001/plone/front-page/@navigation",
+      "schema": "http://localhost:55001/plone/front-page/@schema",
+      "workflow": {
+        "history": [
+          {
+            "action": null, 
+            "actor": "test_user_1_", 
+            "comments": "", 
+            "review_state": "private", 
+            "time": "2016-10-21T19:00:00+00:00"
+          }
+        ], 
+        "transitions": [
+          {
+            "@id": "http://localhost:55001/plone/front-page/@workflow/publish", 
+            "title": "Publish"
+          }, 
+          {
+            "@id": "http://localhost:55001/plone/front-page/@workflow/submit", 
+            "title": "Submit for publication"
+          }
+        ]
+      },
+    },
+    "UID": "1f699ffa110e45afb1ba502f75f7ec33",
+    "title": "Welcome to Plone"
+  }
+
+
+Current implementation
+----------------------
+
+Request:
+
+..  http:example:: curl httpie python-requests
+    :request: _json/expansion.req
+
+Response:
+
+.. literalinclude:: _json/expansion.resp
+   :language: http
\ No newline at end of file
diff --git a/docs/source/index.rst b/docs/source/index.rst
index e7016298..ea4278fd 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -26,6 +26,7 @@ Contents
    batching
    comments
    copymove
+   expansion
    workflow
    sharing
    registry
diff --git a/src/plone/restapi/tests/test_documentation.py b/src/plone/restapi/tests/test_documentation.py
index 4f426083..9ce36a56 100644
--- a/src/plone/restapi/tests/test_documentation.py
+++ b/src/plone/restapi/tests/test_documentation.py
@@ -1104,3 +1104,9 @@ def test_roles_get(self):
         url = '{}/@roles'.format(self.portal_url)
         response = self.api_session.get(url)
         save_request_and_response_for_docs('roles', response)
+
+    def test_documentation_expansion(self):
+        response = self.api_session.get(
+            '/front-page?expand=breadcrumbs,workflow'
+        )
+        save_request_and_response_for_docs('expansion', response)



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