plone.restapi/plone-only-login: Add more examples to expansion docs.
Thomas Buchberger <jenkins-z4DKO/[email protected]> Wed, 26 Jul 2017 07:45:47 -0700 (PDT)
| Newsgroups | gmane.comp.web.zope.plone.cvs |
|---|---|
| Message-ID | <[email protected]> |
Repository: plone.restapi Branch: refs/heads/plone-only-login Date: 2017-07-25T11:48:32+02:00 Author: Timo Stollenwerk (tisto) <[email protected]> Commit: https://github.com/plone/plone.restapi/commit/5261ed050f6d29df65ae0ce9a2c538d0ddc292e2 Add more examples to expansion docs. Files changed: A docs/source/_json/expansion_expanded.req A docs/source/_json/expansion_expanded.resp A docs/source/_json/expansion_expanded_full.req A docs/source/_json/expansion_expanded_full.resp M docs/source/_json/expansion.req M docs/source/_json/expansion.resp M docs/source/expansion.rst M src/plone/restapi/tests/test_documentation.py diff --git a/docs/source/_json/expansion.req b/docs/source/_json/expansion.req index f9df6e4c..e2d9438e 100644 --- a/docs/source/_json/expansion.req +++ b/docs/source/_json/expansion.req @@ -1,3 +1,3 @@ -GET /plone/front-page?expand=breadcrumbs,workflow HTTP/1.1 +GET /plone/front-page HTTP/1.1 Accept: application/json Authorization: Basic YWRtaW46c2VjcmV0 diff --git a/docs/source/_json/expansion.resp b/docs/source/_json/expansion.resp index 69711721..e3aadc15 100644 --- a/docs/source/_json/expansion.resp +++ b/docs/source/_json/expansion.resp @@ -3,12 +3,9 @@ Content-Type: application/json { "@components": { - "breadcrumbs": [ - { - "title": "Welcome to Plone", - "url": "http://localhost:55001/plone/front-page" - } - ], + "breadcrumbs": { + "@id": "http://localhost:55001/plone/front-page/@components/breadcrumbs" + }, "navigation": { "@id": "http://localhost:55001/plone/front-page/@components/navigation" } @@ -16,29 +13,10 @@ Content-Type: application/json "@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" - } - ] + "@id": "http://localhost:55001/plone/front-page/@workflow" }, - "UID": "24f0d86c37ee4ebc889baa39bab56b20", - "allow_discussion": true, + "UID": "SomeUUID000000000000000000000001", + "allow_discussion": null, "changeNote": "", "contributors": [], "created": "2016-01-21T01:14:48+00:00", diff --git a/docs/source/_json/expansion_expanded.req b/docs/source/_json/expansion_expanded.req new file mode 100644 index 00000000..f9df6e4c --- /dev/null +++ b/docs/source/_json/expansion_expanded.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_expanded.resp b/docs/source/_json/expansion_expanded.resp new file mode 100644 index 00000000..e0589029 --- /dev/null +++ b/docs/source/_json/expansion_expanded.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": "SomeUUID000000000000000000000001", + "allow_discussion": null, + "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/_json/expansion_expanded_full.req b/docs/source/_json/expansion_expanded_full.req new file mode 100644 index 00000000..14718682 --- /dev/null +++ b/docs/source/_json/expansion_expanded_full.req @@ -0,0 +1,3 @@ +GET /plone/front-page?expand=breadcrumbs,navigation,workflow HTTP/1.1 +Accept: application/json +Authorization: Basic YWRtaW46c2VjcmV0 diff --git a/docs/source/_json/expansion_expanded_full.resp b/docs/source/_json/expansion_expanded_full.resp new file mode 100644 index 00000000..eafc9360 --- /dev/null +++ b/docs/source/_json/expansion_expanded_full.resp @@ -0,0 +1,86 @@ +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "@components": { + "breadcrumbs": [ + { + "title": "Welcome to Plone", + "url": "http://localhost:55001/plone/front-page" + } + ], + "navigation": [ + { + "title": "Home", + "url": "http://localhost:55001/plone" + }, + { + "title": "Welcome to Plone", + "url": "http://localhost:55001/plone/front-page" + } + ] + }, + "@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": "SomeUUID000000000000000000000001", + "allow_discussion": null, + "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 index cc830a7e..a8f5052a 100644 --- a/docs/source/expansion.rst +++ b/docs/source/expansion.rst @@ -1,16 +1,16 @@ Expansion ========= -Expansion is a mechanism in plone.restapi to embed additional "components", -such as navigation, breadcrumbs, schema, or workflow within the main content +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" within the document GET +workflow switcher. Instead of doing three individual requests, you can just +expand the breadcrumbs and the workflow "components" within the document GET request. -The list of expandable components is listed in the "@components" attribute +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 @@ -31,12 +31,22 @@ in the reponse of any content GET request:: ... } -In order to expand and embed one or more components, use the "expand" GET +Request Unexpanded: + +.. http:example:: curl httpie python-requests + :request: _json/expansion.req + +Response Unexpanded: + +.. literalinclude:: _json/expansion.resp + :language: http + +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:: +component:: - GET /plone/front-page?expand=breadcrumbs,workflow HTTP/1.1 + GET /plone/front-page?expand=breadcrumbs HTTP/1.1 Accept: application/json Authorization: Basic YWRtaW46c2VjcmV0 @@ -45,10 +55,10 @@ and the "workflow" components:: "@type": "Document", "@components": { "breadcrumbs": { - "@id": "http://localhost:55001/plone/front-page/@components/breadcrumbs", + "@id": "http://localhost:55001/plone/front-page/@components/breadcrumbs", "items": [ { - "title": "Welcome to Plone", + "title": "Welcome to Plone", "url": "http://localhost:55001/plone/front-page" } ] @@ -58,20 +68,20 @@ and the "workflow" components:: "workflow": { "history": [ { - "action": null, - "actor": "test_user_1_", - "comments": "", - "review_state": "private", + "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", + "@id": "http://localhost:55001/plone/front-page/@workflow/publish", "title": "Publish" - }, + }, { - "@id": "http://localhost:55001/plone/front-page/@workflow/submit", + "@id": "http://localhost:55001/plone/front-page/@workflow/submit", "title": "Submit for publication" } ] @@ -81,16 +91,22 @@ and the "workflow" components:: "title": "Welcome to Plone" } +Request Expanded: + +.. http:example:: curl httpie python-requests + :request: _json/expansion_expanded.req -Current implementation ----------------------- +Response Expanded: -Request: +.. literalinclude:: _json/expansion_expanded.resp + :language: http + +Here is an exaxmple of a request that expands all possible expansions: .. http:example:: curl httpie python-requests - :request: _json/expansion.req + :request: _json/expansion_expanded_full.req -Response: +And the response: -.. literalinclude:: _json/expansion.resp +.. literalinclude:: _json/expansion_expanded_full.resp :language: http diff --git a/src/plone/restapi/tests/test_documentation.py b/src/plone/restapi/tests/test_documentation.py index 9ce36a56..dd66c871 100644 --- a/src/plone/restapi/tests/test_documentation.py +++ b/src/plone/restapi/tests/test_documentation.py @@ -826,6 +826,24 @@ def test_documentation_sharing_search(self): ) save_request_and_response_for_docs('sharing_search', response) + def test_documentation_expansion(self): + response = self.api_session.get( + '/front-page' + ) + save_request_and_response_for_docs('expansion', response) + + def test_documentation_expansion_expanded(self): + response = self.api_session.get( + '/front-page?expand=breadcrumbs' + ) + save_request_and_response_for_docs('expansion_expanded', response) + + def test_documentation_expansion_expanded_full(self): + response = self.api_session.get( + '/front-page?expand=breadcrumbs,navigation,schema,workflow' + ) + save_request_and_response_for_docs('expansion_expanded_full', response) + def test_history_get(self): self.document.setTitle('My new title') url = '{}/@history'.format(self.document.absolute_url()) ------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot