plone.restapi Documentation Release 1.0a1 Plone Foundation Sep 30, 2021 Table of Contents 1 Introduction 1 2 Authentication 31 3 Explore the API using Postman 35 4 Content Manipulation 39 5 Volto Blocks support 55 6 History 59 7 Batching 63 8 Add-ons 67 9 Comments 73 10 Copy / Move 79 11 Expansion 83 12 Portal Actions 93 13 Workflow 97 14 Working Copy 101 15 Locking 109 16 Sharing 115 17 Registry 121 18 Types 133 19 Types Schema 163 20 Users 173 i 21 Groups 187 22 Principals 195 23 Roles 197 24 Components 199 25 Breadcrumbs 201 26 Navigation 203 27 Context Navigation 207 28 Serialization 211 29 Search 217 30 TUS resumable upload 225 31 Vocabularies and Sources 231 32 Control Panels 243 33 Tiles 269 34 Querystring 271 35 Querystring Search 303 36 Customizing the API 305 37 Conventions 307 38 Translations 311 39 Email Send 319 40 i18n: internationalization of screen messages 321 41 Email Notification 331 42 Upgrade Guide 333 43 Contributing to plone.restapi 349 44 System 351 45 Database 353 46 Introduction 355 47 Documentation 357 48 Getting started 359 49 Installation 361 50 Contribute 363 ii 51 Examples 365 52 Support 367 53 License 369 HTTP Routing Table 371 Index 373 iii iv CHAPTER 1 Introduction API Browser Quick Guide It can make your life easier if you use some kind of API browser application to explore the API when diving into this documentation. • We recommend to use the free Postman browser plugin. • For easy onboarding take a look at our Explore the API using Postman Quick-Guide. A hypermedia API provides an entry point to the API, which contains hyperlinks the clients can follow. Just like a human user of a regular website, who knows the initial URL of a website and then follows hyperlinks to navigate through the site. This has the advantage that the client only needs to understand how to detect and follow links. The URLs (apart from the inital entry point) and other details of the API can change without breaking the client. The entry point to the Plone RESTful API is the portal root. The client can ask for a REST API response by setting the 'Accept' HTTP header to 'application/json': http GET /plone HTTP/1.1 Accept: application/json Authorization: Basic YWRtaW46c2VjcmV0 curl curl -i http://nohost/plone -H 'Accept: application/json' --user admin:secret httpie http http://nohost/plone Accept:application/json -a admin:secret python-requests 1 plone.restapi Documentation, Release 1.0a1 requests.get('http://nohost/plone', headers={'Accept':'application/json'}, auth=( ,!'admin','secret')) This uses so-called ‘content negotiation’ 1.1 Content Negotiation Content negotiation is a mechanism defined in the HTTP specification that makes it possible to serve different versions of a document (or more generally, a resource representation) at the same URI, so that user agents can specify which version fit their capabilities the best. The user agent (or the REST consumer) can ask for a specific representation by providing an Accept HTTP header that lists acceptable media types (e.g. JSON): GET/ Accept: application/json The server is then able to supply the version of the resource that best fits the user agent’s needs. This is reflected in the Content-Type header: HTTP 200OK Content-Type: application/json { 'data':... } The server will then respond with the portal root in the JSON format: HTTP/1.1 200OK Content-Type: application/json { "@components":{ "actions":{ "@id": "http://localhost:55001/plone/@actions" }, "breadcrumbs":{ "@id": "http://localhost:55001/plone/@breadcrumbs" }, "contextnavigation":{ "@id": "http://localhost:55001/plone/@contextnavigation" }, "navigation":{ "@id": "http://localhost:55001/plone/@navigation" } }, "@id": "http://localhost:55001/plone", "@type": "Plone Site", "blocks": {}, "blocks_layout": {}, "description":"", "id": "plone", "is_folderish": true, "items":[ (continues on next page) 2 Chapter 1. Introduction plone.restapi Documentation, Release 1.0a1 (continued from previous page) { "@id": "http://localhost:55001/plone/front-page", "@type": "Document", "description": "Congratulations! You have successfully installed Plone.", "review_state": "private", "title": "Welcome to Plone" } ], "items_total":1, "parent": {}, "title": "Plone site" } @id is a unique identifier for resources (IRIs). The @id property can be used to navigate through the web API by following the links. @type sets the data type of a node or typed value items is a list that contains all objects within that resource. A client application can “follow” the links (by calling the @id property) to other resources. This allows to build a losely coupled client that does not break if some of the URLs change, only the entry point of the entire API (in our case the portal root) needs to be known in advance. Another example, this time showing a request and response for a document. Click on the buttons below to show the different syntaxes for the request. http GET /plone/front-page HTTP/1.1 Accept: application/json Authorization: Basic YWRtaW46c2VjcmV0 curl curl -i 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')) HTTP/1.1 200OK Content-Type: application/json { "@components":{ "actions":{ "@id": "http://localhost:55001/plone/front-page/@actions" }, "breadcrumbs":{ "@id": "http://localhost:55001/plone/front-page/@breadcrumbs" }, "contextnavigation":{ (continues on next page) 1.1. Content Negotiation 3 plone.restapi Documentation, Release 1.0a1 (continued from previous page) "@id": "http://localhost:55001/plone/front-page/@contextnavigation" }, "navigation":{ "@id": "http://localhost:55001/plone/front-page/@navigation" }, "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", "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", "next_item": {}, "parent":{ "@id": "http://localhost:55001/plone", "@type": "Plone Site", "description":"", "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", "version": "current", (continues on next page) 4 Chapter 1. Introduction plone.restapi Documentation, Release 1.0a1 (continued from previous page) "versioning_enabled": true, "working_copy": null, "working_copy_of": null } And so on, see 1.2 Plone Content How to get all standard Plone content representations. The syntax is given in various tools, click on ‘curl’, ‘http-request’ or ‘python-requests’ to see examples. Note: For folderish types, collections or search results, the results will be batched if the size of the resultset exceeds the batch size. See Batching for more details on how to work with batched results. 1.2.1 Plone Portal Root: http GET /plone HTTP/1.1 Accept: application/json Authorization: Basic YWRtaW46c2VjcmV0 curl curl -i http://nohost/plone -H 'Accept: application/json' --user admin:secret httpie http http://nohost/plone Accept:application/json -a admin:secret python-requests requests.get('http://nohost/plone', headers={'Accept':'application/json'}, ,!auth=('admin','secret')) HTTP/1.1 200OK Content-Type: application/json { "@components":{ "actions":{ "@id": "http://localhost:55001/plone/@actions" }, "breadcrumbs":{ "@id": "http://localhost:55001/plone/@breadcrumbs" }, "contextnavigation":{ "@id": "http://localhost:55001/plone/@contextnavigation" }, (continues on next page) 1.2. Plone Content 5 plone.restapi Documentation, Release 1.0a1 (continued from previous page) "navigation":{ "@id": "http://localhost:55001/plone/@navigation" } }, "@id": "http://localhost:55001/plone", "@type": "Plone Site", "blocks": {}, "blocks_layout": {}, "description":"", "id": "plone", "is_folderish": true, "items":[ { "@id": "http://localhost:55001/plone/front-page", "@type": "Document", "description": "Congratulations! You have successfully installed ,!Plone.", "review_state": "private", "title": "Welcome to Plone" } ], "items_total":1, "parent": {}, "title": "Plone site" } 1.2.2 Plone Folder: http GET /plone/folder HTTP/1.1 Accept: application/json Authorization: Basic YWRtaW46c2VjcmV0 curl curl -i http://nohost/plone/folder -H 'Accept: application/json' --user ,!admin:secret httpie http http://nohost/plone/folder Accept:application/json -a admin:secret python-requests requests.get('http://nohost/plone/folder', headers={'Accept':'application/ ,!json'}, auth=('admin','secret')) HTTP/1.1 200OK Content-Type: application/json { "@components":{ "actions":{ (continues on next page) 6 Chapter 1. Introduction plone.restapi Documentation, Release 1.0a1 (continued from previous