Expansion#
Expansion is a mechanism in plone.restapi to embed additional "components"—such as navigation, breadcrumbs, schema, or workflows—within the main content response.
This helps the API consumers avoid unnecessary requests.
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 expand the breadcrumbs and the workflow "components" within the document GET request.
The following is a list of components that support expansion.
You can also get the list expandable components by inspecting the @components attribute in the response of any content GET request, as shown in the following example.
GET /plone/front-page HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
{
"@id": "http://localhost:55001/plone/front-page",
"@type": "Document",
"@components": [
{
"@id": "http://localhost:55001/plone/front-page/@actions"
},
{
"@id": "http://localhost:55001/plone/front-page/@breadcrumbs"
},
{
"@id": "http://localhost:55001/plone/front-page/@navigation"
},
{
"@id": "http://localhost:55001/plone/front-page/@types"
},
{
"@id": "http://localhost:55001/plone/front-page/@workflow"
},
{
"more components": "..."
}
],
"UID": "1f699ffa110e45afb1ba502f75f7ec33",
"title": "Welcome to Plone",
"more attributes": "..."
}
Request (unexpanded):
http
GET /plone/front-page HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl
curl -i -X GET http://nohost/plone/front-page -H "Accept: application/json" --user admin:secret
httpie
http http://nohost/plone/front-page Accept:application/json -a admin:secret
python-requests
requests.get('http://nohost/plone/front-page', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
Response (unexpanded):
HTTP/1.1 200 OK
Content-Type: application/json
{
"@components": {
"actions": {
"@id": "http://localhost:55001/plone/front-page/@actions"
},
"aliases": {
"@id": "http://localhost:55001/plone/front-page/@aliases"
},
"breadcrumbs": {
"@id": "http://localhost:55001/plone/front-page/@breadcrumbs"
},
"contextnavigation": {
"@id": "http://localhost:55001/plone/front-page/@contextnavigation"
},
"navigation": {
"@id": "http://localhost:55001/plone/front-page/@navigation"
},
"navroot": {
"@id": "http://localhost:55001/plone/front-page/@navroot"
},
"types": {
"@id": "http://localhost:55001/plone/front-page/@types"
},
"workflow": {
"@id": "http://localhost:55001/plone/front-page/@workflow"
}
},
"@id": "http://localhost:55001/plone/front-page",
"@type": "Document",
"UID": "SomeUUID000000000000000000000001",
"allow_discussion": false,
"changeNote": "",
"contributors": [],
"created": "1995-07-31T13:45:00+00:00",
"creators": [
"test_user_1_"
],
"description": "Congratulations! You have successfully installed Plone.",
"effective": null,
"exclude_from_nav": false,
"expires": null,
"id": "front-page",
"is_folderish": false,
"language": "",
"layout": "document_view",
"lock": {
"locked": false,
"stealable": true
},
"modified": "1995-07-31T17:30:00+00:00",
"next_item": {},
"parent": {
"@id": "http://localhost:55001/plone",
"@type": "Plone Site",
"description": "",
"title": "Plone site",
"type_title": "Plone Site"
},
"previous_item": {},
"relatedItems": [],
"review_state": "private",
"rights": "",
"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",
"type_title": "Page",
"version": "current",
"versioning_enabled": true,
"working_copy": null,
"working_copy_of": null
}
In order to expand and embed one or more components, use the GET parameter expand, 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 component:
http
GET /plone/front-page?expand=breadcrumbs HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl
curl -i -X GET 'http://nohost/plone/front-page?expand=breadcrumbs' -H "Accept: application/json" --user admin:secret
httpie
http 'http://nohost/plone/front-page?expand=breadcrumbs' Accept:application/json -a admin:secret
python-requests
requests.get('http://nohost/plone/front-page?expand=breadcrumbs', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
Response (breadcrumbs expanded):
HTTP/1.1 200 OK
Content-Type: application/json
{
"@components": {
"actions": {
"@id": "http://localhost:55001/plone/front-page/@actions"
},
"aliases": {
"@id": "http://localhost:55001/plone/front-page/@aliases"
},
"breadcrumbs": {
"@id": "http://localhost:55001/plone/front-page/@breadcrumbs",
"items": [
{
"@id": "http://localhost:55001/plone/front-page",
"title": "Welcome to Plone"
}
],
"root": "http://localhost:55001/plone"
},
"contextnavigation": {
"@id": "http://localhost:55001/plone/front-page/@contextnavigation"
},
"navigation": {
"@id": "http://localhost:55001/plone/front-page/@navigation"
},
"navroot": {
"@id": "http://localhost:55001/plone/front-page/@navroot"
},
"types": {
"@id": "http://localhost:55001/plone/front-page/@types"
},
"workflow": {
"@id": "http://localhost:55001/plone/front-page/@workflow"
}
},
"@id": "http://localhost:55001/plone/front-page",
"@type": "Document",
"UID": "SomeUUID000000000000000000000001",
"allow_discussion": false,
"changeNote": "",
"contributors": [],
"created": "1995-07-31T13:45:00+00:00",
"creators": [
"test_user_1_"
],
"description": "Congratulations! You have successfully installed Plone.",
"effective": null,
"exclude_from_nav": false,
"expires": null,
"id": "front-page",
"is_folderish": false,
"language": "",
"layout": "document_view",
"lock": {
"locked": false,
"stealable": true
},
"modified": "1995-07-31T17:30:00+00:00",
"next_item": {},
"parent": {
"@id": "http://localhost:55001/plone",
"@type": "Plone Site",
"description": "",
"title": "Plone site",
"type_title": "Plone Site"
},
"previous_item": {},
"relatedItems": [],
"review_state": "private",
"rights": "",
"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",
"type_title": "Page",
"version": "current",
"versioning_enabled": true,
"working_copy": null,
"working_copy_of": null
}
Here is an example of a request that expands all possible expansions:
http
GET /plone/front-page?expand=actions,breadcrumbs,navigation,workflow,types HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl
curl -i -X GET 'http://nohost/plone/front-page?expand=actions,breadcrumbs,navigation,workflow,types' -H "Accept: application/json" --user admin:secret
httpie
http 'http://nohost/plone/front-page?expand=actions,breadcrumbs,navigation,workflow,types' Accept:application/json -a admin:secret
python-requests
requests.get('http://nohost/plone/front-page?expand=actions,breadcrumbs,navigation,workflow,types', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
And the response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"@components": {
"actions": {
"document_actions": [],
"object": [
{
"icon": "toolbar-action/view",
"id": "view",
"title": "View",
"url": "http://localhost:55001/plone/front-page"
},
{
"icon": "toolbar-action/edit",
"id": "edit",
"title": "Edit",
"url": "http://localhost:55001/plone/front-page/edit"
},
{
"icon": "toolbar-action/folderContents",
"id": "folderContents",
"title": "Contents",
"url": "http://localhost:55001/plone/folder_contents"
},
{
"icon": "toolbar-action/history",
"id": "history",
"title": "History",
"url": "http://localhost:55001/plone/front-page/@@historyview"
},
{
"icon": "toolbar-action/sharing",
"id": "local_roles",
"title": "Sharing",
"url": "http://localhost:55001/plone/front-page/@@sharing"
}
],
"object_buttons": [
{
"icon": "plone-cut",
"id": "cut",
"title": "Cut",
"url": "http://localhost:55001/plone/front-page/object_cut"
},
{
"icon": "plone-copy",
"id": "copy",
"title": "Copy",
"url": "http://localhost:55001/plone/front-page/object_copy"
},
{
"icon": "plone-delete",
"id": "delete",
"title": "Delete",
"url": "http://localhost:55001/plone/front-page/delete_confirmation"
},
{
"icon": "plone-rename",
"id": "rename",
"title": "Rename",
"url": "http://localhost:55001/plone/front-page/object_rename"
},
{
"icon": "plone-redirection",
"id": "redirection",
"title": "URL Management",
"url": " http://localhost:55001/plone/front-page/@@manage-aliases"
}
],
"portal_tabs": [
{
"icon": "plone-home",
"id": "index_html",
"title": "Home",
"url": "http://localhost:55001/plone"
}
],
"site_actions": [
{
"icon": "plone-sitemap",
"id": "sitemap",
"title": "Site Map",
"url": "http://localhost:55001/plone/sitemap"
},
{
"icon": "plone-accessibility",
"id": "accessibility",
"title": "Accessibility",
"url": "http://localhost:55001/plone/accessibility-info"
},
{
"icon": "plone-contact-info",
"id": "contact",
"title": "Contact",
"url": "http://localhost:55001/plone/contact-info"
}
],
"user": [
{
"icon": "plone-user",
"id": "preferences",
"title": "Preferences",
"url": "http://localhost:55001/plone/@@personal-preferences"
},
{
"icon": "plone-dashboard",
"id": "dashboard",
"title": "Dashboard",
"url": "http://localhost:55001/plone/dashboard"
},
{
"icon": "plone-controlpanel",
"id": "plone_setup",
"title": "Site Setup",
"url": "http://localhost:55001/plone/@@overview-controlpanel"
},
{
"icon": "plone-logout",
"id": "logout",
"title": "Log out",
"url": "http://localhost:55001/plone/logout"
}
]
},
"aliases": {
"@id": "http://localhost:55001/plone/front-page/@aliases"
},
"breadcrumbs": {
"@id": "http://localhost:55001/plone/front-page/@breadcrumbs",
"items": [
{
"@id": "http://localhost:55001/plone/front-page",
"title": "Welcome to Plone"
}
],
"root": "http://localhost:55001/plone"
},
"contextnavigation": {
"@id": "http://localhost:55001/plone/front-page/@contextnavigation"
},
"navigation": {
"@id": "http://localhost:55001/plone/front-page/@navigation",
"items": [
{
"@id": "http://localhost:55001/plone",
"description": "",
"items": [],
"review_state": null,
"title": "Home"
},
{
"@id": "http://localhost:55001/plone/front-page",
"description": "Congratulations! You have successfully installed Plone.",
"items": [],
"review_state": "private",
"title": "Welcome to Plone"
}
]
},
"navroot": {
"@id": "http://localhost:55001/plone/front-page/@navroot"
},
"types": [
{
"@id": "http://localhost:55001/plone/@types/Collection",
"addable": false,
"id": "Collection",
"immediately_addable": false,
"title": "Collection"
},
{
"@id": "http://localhost:55001/plone/@types/DXTestDocument",
"addable": false,
"id": "DXTestDocument",
"immediately_addable": false,
"title": "DX Test Document"
},
{
"@id": "http://localhost:55001/plone/@types/Event",
"addable": false,
"id": "Event",
"immediately_addable": false,
"title": "Event"
},
{
"@id": "http://localhost:55001/plone/@types/File",
"addable": false,
"id": "File",
"immediately_addable": false,
"title": "File"
},
{
"@id": "http://localhost:55001/plone/@types/Folder",
"addable": false,
"id": "Folder",
"immediately_addable": false,
"title": "Folder"
},
{
"@id": "http://localhost:55001/plone/@types/Image",
"addable": false,
"id": "Image",
"immediately_addable": false,
"title": "Image"
},
{
"@id": "http://localhost:55001/plone/@types/Link",
"addable": false,
"id": "Link",
"immediately_addable": false,
"title": "Link"
},
{
"@id": "http://localhost:55001/plone/@types/News Item",
"addable": false,
"id": "News Item",
"immediately_addable": false,
"title": "News Item"
},
{
"@id": "http://localhost:55001/plone/@types/Document",
"addable": false,
"id": "Document",
"immediately_addable": false,
"title": "Page"
}
],
"workflow": {
"@id": "http://localhost:55001/plone/front-page/@workflow",
"history": [
{
"action": null,
"actor": "test_user_1_",
"comments": "",
"review_state": "private",
"time": "1995-07-31T17:30:00+00:00",
"title": "Private"
}
],
"state": {
"id": "private",
"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",
"@type": "Document",
"UID": "SomeUUID000000000000000000000001",
"allow_discussion": false,
"changeNote": "",
"contributors": [],
"created": "1995-07-31T13:45:00+00:00",
"creators": [
"test_user_1_"
],
"description": "Congratulations! You have successfully installed Plone.",
"effective": null,
"exclude_from_nav": false,
"expires": null,
"id": "front-page",
"is_folderish": false,
"language": "",
"layout": "document_view",
"lock": {
"locked": false,
"stealable": true
},
"modified": "1995-07-31T17:30:00+00:00",
"next_item": {},
"parent": {
"@id": "http://localhost:55001/plone",
"@type": "Plone Site",
"description": "",
"title": "Plone site",
"type_title": "Plone Site"
},
"previous_item": {},
"relatedItems": [],
"review_state": "private",
"rights": "",
"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",
"type_title": "Page",
"version": "current",
"versioning_enabled": true,
"working_copy": null,
"working_copy_of": null
}