plone.restapi: A RESTful hypermedia API for Plone.¶

Contents¶

Introduction¶

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

requests.get('http://nohost/plone', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

This uses so-called ‘content negotiation’

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 200 OK
Content-Type: application/json

{
  'data': ...
}

The server will then respond with the portal root in the JSON format:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/@navigation"
    }
  }, 
  "@id": "http://localhost:55001/plone", 
  "@type": "Plone Site", 
  "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": {}, 
  "tiles": {}, 
  "tiles_layout": {}, 
  "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 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/front-page/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/front-page/@breadcrumbs"
    }, 
    "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", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "table_of_contents": null, 
  "text": {
    "content-type": "text/plain", 
    "data": "<p>If you&#x27;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", 
  "versioning_enabled": true
}

And so on, see

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.

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 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/@navigation"
    }
  }, 
  "@id": "http://localhost:55001/plone", 
  "@type": "Plone Site", 
  "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": {}, 
  "tiles": {}, 
  "tiles_layout": {}, 
  "title": "Plone site"
}

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 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/folder/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/folder/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/folder/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/folder/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/folder/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/folder", 
  "@type": "Folder", 
  "UID": "SomeUUID000000000000000000000002", 
  "allow_discussion": false, 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "test_user_1_"
  ], 
  "description": "This is a folder with two documents", 
  "effective": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "id": "folder", 
  "is_folderish": true, 
  "items": [
    {
      "@id": "http://localhost:55001/plone/folder/doc1", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "A document within a folder"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder/doc2", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "A document within a folder"
    }
  ], 
  "items_total": 2, 
  "language": "", 
  "layout": "listing_view", 
  "modified": "1995-07-31T17:30:00", 
  "nextPreviousEnabled": false, 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "title": "My Folder", 
  "version": "current"
}

Plone Document:¶

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 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/front-page/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/front-page/@breadcrumbs"
    }, 
    "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", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "table_of_contents": null, 
  "text": {
    "content-type": "text/plain", 
    "data": "<p>If you&#x27;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", 
  "versioning_enabled": true
}

News Item:¶

Note

Here we show uuid1 as an example uid for all image scales because this documentation is autogenerated by the tests. When running in a real application, these uuid1 values will be exchanged by proper uuid4 values.

http

GET /plone/newsitem HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/newsitem -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/newsitem Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/newsitem', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/newsitem/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/newsitem/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/newsitem/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/newsitem/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/newsitem/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/newsitem", 
  "@type": "News Item", 
  "UID": "SomeUUID000000000000000000000002", 
  "allow_discussion": false, 
  "changeNote": "", 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "test_user_1_"
  ], 
  "description": "This is a news item", 
  "effective": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "id": "newsitem", 
  "image": {
    "content-type": "image/png", 
    "download": "http://localhost:55001/plone/newsitem/@@images/uuid1.png", 
    "filename": "image.png", 
    "height": 56, 
    "scales": {
      "icon": {
        "download": "http://localhost:55001/plone/newsitem/@@images/uuid1.png", 
        "height": 8, 
        "width": 32
      }, 
      "large": {
        "download": "http://localhost:55001/plone/newsitem/@@images/uuid1.png", 
        "height": 56, 
        "width": 215
      }, 
      "listing": {
        "download": "http://localhost:55001/plone/newsitem/@@images/uuid1.png", 
        "height": 4, 
        "width": 16
      }, 
      "mini": {
        "download": "http://localhost:55001/plone/newsitem/@@images/uuid1.png", 
        "height": 52, 
        "width": 200
      }, 
      "preview": {
        "download": "http://localhost:55001/plone/newsitem/@@images/uuid1.png", 
        "height": 56, 
        "width": 215
      }, 
      "thumb": {
        "download": "http://localhost:55001/plone/newsitem/@@images/uuid1.png", 
        "height": 33, 
        "width": 128
      }, 
      "tile": {
        "download": "http://localhost:55001/plone/newsitem/@@images/uuid1.png", 
        "height": 16, 
        "width": 64
      }
    }, 
    "size": 1185, 
    "width": 215
  }, 
  "image_caption": "This is an image caption.", 
  "is_folderish": false, 
  "language": "", 
  "layout": "newsitem_view", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "text": {
    "content-type": "text/plain", 
    "data": "<p>Lorem ipsum</p>", 
    "encoding": "utf-8"
  }, 
  "title": "My News Item", 
  "version": "current", 
  "versioning_enabled": true
}

Event:¶

http

GET /plone/event HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/event -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/event Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/event', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/event/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/event/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/event/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/event/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/event/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/event", 
  "@type": "Event", 
  "UID": "SomeUUID000000000000000000000002", 
  "allow_discussion": false, 
  "attendees": [], 
  "changeNote": "", 
  "contact_email": null, 
  "contact_name": null, 
  "contact_phone": null, 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "test_user_1_"
  ], 
  "description": "This is an event", 
  "effective": null, 
  "end": "2013-01-01T12:00:00", 
  "event_url": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "id": "event", 
  "is_folderish": false, 
  "language": "", 
  "layout": "event_view", 
  "location": null, 
  "modified": "1995-07-31T17:30:00", 
  "open_end": false, 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "recurrence": null, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "start": "2013-01-01T10:00:00", 
  "subjects": [], 
  "sync_uid": null, 
  "text": null, 
  "title": "Event", 
  "version": "current", 
  "versioning_enabled": true, 
  "whole_day": false
}

Image:¶

Note

Here we show uuid1 as an example uid for all image scales because this documentation is autogenerated by the tests. When running in a real application, these uuid1 values will be exchanged by proper uuid4 values.

http

GET /plone/image HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/image -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/image Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/image', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/image/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/image/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/image/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/image/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/image/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/image", 
  "@type": "Image", 
  "UID": "SomeUUID000000000000000000000002", 
  "allow_discussion": false, 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "test_user_1_"
  ], 
  "description": "This is an image", 
  "effective": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "id": "image", 
  "image": {
    "content-type": "image/png", 
    "download": "http://localhost:55001/plone/image/@@images/uuid1.png", 
    "filename": "image.png", 
    "height": 56, 
    "scales": {
      "icon": {
        "download": "http://localhost:55001/plone/image/@@images/uuid1.png", 
        "height": 8, 
        "width": 32
      }, 
      "large": {
        "download": "http://localhost:55001/plone/image/@@images/uuid1.png", 
        "height": 56, 
        "width": 215
      }, 
      "listing": {
        "download": "http://localhost:55001/plone/image/@@images/uuid1.png", 
        "height": 4, 
        "width": 16
      }, 
      "mini": {
        "download": "http://localhost:55001/plone/image/@@images/uuid1.png", 
        "height": 52, 
        "width": 200
      }, 
      "preview": {
        "download": "http://localhost:55001/plone/image/@@images/uuid1.png", 
        "height": 56, 
        "width": 215
      }, 
      "thumb": {
        "download": "http://localhost:55001/plone/image/@@images/uuid1.png", 
        "height": 33, 
        "width": 128
      }, 
      "tile": {
        "download": "http://localhost:55001/plone/image/@@images/uuid1.png", 
        "height": 16, 
        "width": 64
      }
    }, 
    "size": 1185, 
    "width": 215
  }, 
  "is_folderish": false, 
  "language": "", 
  "layout": "image_view", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "relatedItems": [], 
  "review_state": null, 
  "rights": "", 
  "subjects": [], 
  "title": "My Image", 
  "version": "current"
}

File:¶

http

GET /plone/file HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/file -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/file Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/file', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/file/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/file/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/file/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/file/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/file/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/file", 
  "@type": "File", 
  "UID": "SomeUUID000000000000000000000002", 
  "allow_discussion": false, 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "test_user_1_"
  ], 
  "description": "This is a file", 
  "effective": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "file": {
    "content-type": "application/pdf", 
    "download": "http://localhost:55001/plone/file/@@download/file", 
    "filename": "file.pdf", 
    "size": 74429
  }, 
  "id": "file", 
  "is_folderish": false, 
  "language": "", 
  "layout": "file_view", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "relatedItems": [], 
  "review_state": null, 
  "rights": "", 
  "subjects": [], 
  "title": "My File", 
  "version": "current"
}

Link:¶

http

GET /plone/link HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/link -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/link Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/link', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/link/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/link/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/link/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/link/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/link/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/link", 
  "@type": "Link", 
  "UID": "SomeUUID000000000000000000000002", 
  "allow_discussion": false, 
  "changeNote": "", 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "test_user_1_"
  ], 
  "description": "This is a link", 
  "effective": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "id": "link", 
  "is_folderish": false, 
  "language": "", 
  "layout": "link_redirect_view", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "remoteUrl": null, 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "title": "My Link", 
  "version": "current", 
  "versioning_enabled": true
}

Collection:¶

http

GET /plone/collection HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/collection -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/collection Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/collection', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/collection/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/collection/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/collection/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/collection/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/collection/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/collection", 
  "@type": "Collection", 
  "UID": "SomeUUID000000000000000000000002", 
  "allow_discussion": false, 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "test_user_1_"
  ], 
  "customViewFields": [
    {
      "title": "Title", 
      "token": "Title"
    }, 
    {
      "title": "Creator", 
      "token": "Creator"
    }, 
    {
      "title": "Type", 
      "token": "Type"
    }, 
    {
      "title": "ModificationDate", 
      "token": "ModificationDate"
    }
  ], 
  "description": "This is a collection with two documents", 
  "effective": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "id": "collection", 
  "is_folderish": false, 
  "item_count": 30, 
  "items": [
    {
      "@id": "http://localhost:55001/plone/front-page", 
      "@type": "Document", 
      "description": "Congratulations! You have successfully installed Plone.", 
      "review_state": "private", 
      "title": "Welcome to Plone"
    }, 
    {
      "@id": "http://localhost:55001/plone/doc1", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "Document 1"
    }, 
    {
      "@id": "http://localhost:55001/plone/doc2", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "Document 2"
    }
  ], 
  "items_total": 3, 
  "language": "", 
  "layout": "listing_view", 
  "limit": 1000, 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "query": [
    {
      "i": "portal_type", 
      "o": "plone.app.querystring.operation.string.is", 
      "v": "Document"
    }
  ], 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "sort_on": null, 
  "sort_reversed": null, 
  "subjects": [], 
  "text": null, 
  "title": "My Collection", 
  "version": "current"
}

Authentication¶

plone.restapi uses Plone PAS for Authentication.

That means that any authentication method supported by an installed PAS Plugin should work, assuming it’s an authentication method that makes sense to use with an API.

For example, to authenticate using HTTP basic auth, you’d set an Authorization header:

GET /Plone HTTP/1.1
Authorization: Basic Zm9vYmFyOmZvb2Jhcgo=
Accept: application/json

HTTP client libraries usually contain helper functions to produce a proper Authorization header for you based on given credentials.

Using the requests library, you’d set up a session with basic auth like this:

import requests

session = requests.Session()
session.auth = ('username', 'password')
session.headers.update({'Accept': 'application/json'})

response = session.get(url)

Or the same example using curl:

curl -u username:password -H 'Accept:application/json' $URL

JSON Web Tokens (JWT)¶

plone.restapi includes a Plone PAS plugin for authentication with JWT. The plugin is installed automatically when installing the product.

Acquiring a token (@login)¶

A JWT token can be acquired by posting a user’s credentials to the @login endpoint.

http

POST /plone/@login HTTP/1.1
Accept: application/json
Content-Type: application/json

{
    "login": "admin",
    "password": "secret"
}

curl

curl -i -X POST http://nohost/plone/@login -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"login": "admin", "password": "secret"}'

httpie

echo '{
  "login": "admin",
  "password": "secret"
}' | http POST http://nohost/plone/@login Accept:application/json Content-Type:application/json

python-requests

requests.post('http://nohost/plone/@login', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'login': 'admin',
    'password': 'secret',
})

The server responds with a JSON object containing the token.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo"
}

Authenticating with a token¶

The token can now be used in subsequent requests by including it in the Authorization header with the Bearer scheme:

http

GET /plone/ HTTP/1.1
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo

curl

curl -i http://nohost/plone/ -H 'Accept: application/json' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo'

httpie

http http://nohost/plone/ Accept:application/json Authorization:'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo'

python-requests

requests.get('http://nohost/plone/', headers={
    'Accept': 'application/json',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo',
})

Renewing a token (@login-renew)¶

By default the token will expire after 12 hours and thus must be renewed before expiration. To renew the token simply post to the @login-renew endpoint.

http

POST /plone/@login-renew HTTP/1.1
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo

curl

curl -i -X POST http://nohost/plone/@login-renew -H 'Accept: application/json' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo'

httpie

http POST http://nohost/plone/@login-renew Accept:application/json Authorization:'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo'

python-requests

requests.post('http://nohost/plone/@login-renew', headers={
    'Accept': 'application/json',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo',
})

The server returns a JSON object with a new token:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo"
}

Invalidating a token (@logout)¶

The @logout endpoint can be used to invalidate tokens. However by default tokens are not persisted on the server and thus can not be invalidated. To enable token invaldiation, activate the store_tokes option in the PAS plugin. If you need tokens that are valid indefinitely you should also disable the use of Plone’s keyring in the PAS plugin (option use_keyring).

The logout request must contain the existing token in the Authorization header.

http

POST /plone/@logout HTTP/1.1
Accept: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo

curl

curl -i -X POST http://nohost/plone/@logout -H 'Accept: application/json' -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo'

httpie

http POST http://nohost/plone/@logout Accept:application/json Authorization:'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo'

python-requests

requests.post('http://nohost/plone/@logout', headers={
    'Accept': 'application/json',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiIn0.krI8ep0NQHyYYObtXl1ygI4NM2UbHUlZqF7kKnx9JFo',
})

If invalidation succeeds, the server responds with an empty 204 reponse:

HTTP/1.1 204 No Content

Permissions¶

In order for a user to use the REST API, the plone.restapi: Use REST API permission is required.

By default, installing the plone.restapi:default profile will assign this permission to the Anonymous role, so everybody is allowed to use the REST API by default.

If you wish to control in more detail which roles are allowed to use the REST API, please assign this permission accordingly.

As well as the plone.restapi: Use REST API permission some of the common Plone permissions are also required, depending on the particular service. For example, retrieving a resource using GET will require View, adding an object using POST will require Add portal content, and so on.

In order to modify/override this behavior, if your custom service class inherits from plone.restapi.services.Service, just override the method check_permission and add your custom checks accordingly.

Explore the API using Postman¶

To discover the API interactively, using Postman is recommended.

Note

The Chrome-Extension version of Postman is deprecated and it is recommended to use the native app available instead.

Configuration¶

To easily follow links returned by request based on the API,

go to the menu under the wrench icon on the top right
choose Settings
activate the option Retain headers on clicking on links by selecting ON:

postman-retain-headers

This option makes sure, once a HTTP-Header is configured, it will be reused during following requests , if these are initiated by clicking on links resulting from the initial request. This way navigating the structure using the API becomes a snap.

The option Send anonymous usage data to Postman should be deactivated by setting to OFF.

Usage¶

Choose the suitable HTTP Verb to be used for your request. This can be selected using the Postman HTTP Verb -> GET drop-down menu.

Enter the Object URL of the object that should be the target of a request into the URL field right to the HTTP Verb:

postman-request

Now set the appropriate HTTP headers.

The Authorization Header for the authentication related to the right user
The Accept Header to initiate the right behaviour by the API related to this Request.

To set the Authorization Header, there is a reserved tab, that is responsible to generate the final Header based on the authentication method and username + password.

You have to select

in the drop-down menu Basic Auth -> the term Basic Auth as the authentication method
A valid existing user with appropriate permissions

After providing these parameters you can create the resulting Authorization Header and insert it into the prepared request by clicking on Preview Request.

postman-basic-auth

Under the Headers tab you now need to insert in the Accept Header application/json` header as well:

postman-headers

The request is now ready and can be send by clicking on Send button.

The Response of the server is now displayed below the Request. You can easily follow the links on the @id attributes by clicking on them. For every link Postman has prepared another request sharing the same headers that can be send again by licking on the Send button.

postman-response

Conclusion

You can now explore the whole stucture of your application easily via the API using GET requests.

Content Manipulation¶

plone.restapi does not only expose content objects via a RESTful API. The API consumer can create, read, update, and delete a content object. Those operations can be mapped to the HTTP verbs POST (Create), GET (Read), PUT (Update) and DELETE (Delete).

Manipulating resources across the network by using HTTP as an application protocol is one of core principles of the REST architectural pattern. This allows us to interact with a specific resource in a standardized way:

Verb	URL	Action
POST	/folder	Creates a new document within the folder
GET	/folder/{document-id}	Request the current state of the document
PATCH	/folder/{document-id}	Update the document details
DELETE	/folder/{document-id}	Remove the document

Creating a Resource with POST¶

To create a new resource, we send a POST request to the resource container. If we want to create a new document within an existing folder, we send a POST request to that folder:

http

POST /plone/folder HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "@type": "Document",
    "title": "My Document"
}

curl

curl -i -X POST http://nohost/plone/folder -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"@type": "Document", "title": "My Document"}' --user admin:secret

httpie

echo '{
  "@type": "Document",
  "title": "My Document"
}' | http POST http://nohost/plone/folder Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/folder', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    '@type': 'Document',
    'title': 'My Document',
}, auth=('admin', 'secret'))

By setting the ‘Accept’ header, we tell the server that we would like to receive the response in the ‘application/json’ representation format.

The ‘Content-Type’ header indicates that the body uses the ‘application/json’ format.

The request body contains the minimal necessary information needed to create a document (the type and the title). You could set other properties, like “description” here as well.

Successful Response (201 Created)¶

If a resource has been created, the server responds with the 201 Created status code. The ‘Location’ header contains the URL of the newly created resource and the resource representation in the payload:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://localhost:55001/plone/folder/my-document

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/folder/my-document/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/folder/my-document/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/folder/my-document/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/folder/my-document/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/folder/my-document/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/folder/my-document", 
  "@type": "Document", 
  "UID": "SomeUUID000000000000000000000005", 
  "allow_discussion": false, 
  "changeNote": "", 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "admin"
  ], 
  "description": "", 
  "effective": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "id": "my-document", 
  "is_folderish": false, 
  "language": "", 
  "layout": "document_view", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone/folder", 
    "@type": "Folder", 
    "description": "This is a folder with two documents", 
    "review_state": "private", 
    "title": "My Folder"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "table_of_contents": null, 
  "text": null, 
  "title": "My Document", 
  "version": "current", 
  "versioning_enabled": true
}

Unsuccessful Response (400 Bad Request)¶

If the resource could not be created, for instance because the title was missing in the request, the server responds with 400 Bad Request:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  'message': 'Required title field is missing'
}

The response body can contain information about why the request failed.

Unsuccessful Response (500 Internal Server Error)¶

If the server can not properly process a request, it responds with 500 Internal Server Error:

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  'message': 'Internal Server Error'
}

The response body can contain further information such as an error trace or a link to the documentation.

Possible POST Responses¶

Possible server reponses for a POST request are:

201 Created (Resource has been created successfully)
400 Bad Request (malformed request to the service)
500 Internal Server Error (server fault, can not recover internally)

POST Implementation¶

A pseudo-code example of the POST implementation on the server:

try:
    order = createOrder()
    if order == None:
        # Bad Request
        response.setStatus(400)
    else:
        # Created
        response.setStatus(201)
except:
    # Internal Server Error
    response.setStatus(500)

TODO: Link to the real implementation… [

Reading a Resource with GET¶

After a successful POST, we can access the resource by sending a GET request to the resource URL:

http

GET /plone/folder/my-document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/folder/my-document -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/folder/my-document Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/folder/my-document', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Successful Response (200 OK)¶

If a resource has been retrieved successfully, the server responds with 200 OK:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/folder/my-document/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/folder/my-document/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/folder/my-document/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/folder/my-document/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/folder/my-document/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/folder/my-document", 
  "@type": "Document", 
  "UID": "SomeUUID000000000000000000000005", 
  "allow_discussion": false, 
  "changeNote": "", 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "admin"
  ], 
  "description": "", 
  "effective": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "id": "my-document", 
  "is_folderish": false, 
  "language": "", 
  "layout": "document_view", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone/folder", 
    "@type": "Folder", 
    "description": "This is a folder with two documents", 
    "review_state": "private", 
    "title": "My Folder"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "table_of_contents": null, 
  "text": null, 
  "title": "My Document", 
  "version": "current", 
  "versioning_enabled": true
}

For folderish types, their childrens are automatically included in the response as items. To disable the inclusion, add the GET parameter include_items=false to the URL.

By default only basic metadata is included. To include additional metadata, you can specify the names of the properties with the metadata_fields parameter. See also Retrieving additional metadata.

The following example additionaly retrieves the UID and Creator:

http

GET /plone/folder?metadata_fields=UID&metadata_fields=Creator HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/folder?metadata_fields=UID&metadata_fields=Creator' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/folder?metadata_fields=UID&metadata_fields=Creator' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/folder?metadata_fields=UID&metadata_fields=Creator', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/folder/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/folder/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/folder/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/folder/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/folder/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/folder?metadata_fields=UID&metadata_fields=Creator", 
  "@type": "Folder", 
  "UID": "SomeUUID000000000000000000000002", 
  "allow_discussion": false, 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "test_user_1_"
  ], 
  "description": "This is a folder with two documents", 
  "effective": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "id": "folder", 
  "is_folderish": true, 
  "items": [
    {
      "@id": "http://localhost:55001/plone/folder/doc1", 
      "@type": "Document", 
      "Creator": "test_user_1_", 
      "UID": "SomeUUID000000000000000000000003", 
      "description": "", 
      "review_state": "private", 
      "title": "A document within a folder"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder/doc2", 
      "@type": "Document", 
      "Creator": "test_user_1_", 
      "UID": "SomeUUID000000000000000000000004", 
      "description": "", 
      "review_state": "private", 
      "title": "A document within a folder"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder/my-document", 
      "@type": "Document", 
      "Creator": "admin", 
      "UID": "SomeUUID000000000000000000000005", 
      "description": "", 
      "review_state": "private", 
      "title": "My Document"
    }
  ], 
  "items_total": 3, 
  "language": "", 
  "layout": "listing_view", 
  "modified": "1995-07-31T17:30:00", 
  "nextPreviousEnabled": false, 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "title": "My Folder", 
  "version": "current"
}

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.

Unsuccessful response (404 Not Found)¶

If a resource could not be found, the server will respond with 404 Not Found:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  'error': 'NotFound'
}

GET Implementation¶

A pseudo-code example of the GET implementation on the server:

try:
    order = getOrder()
    if order == None:
        # Not Found
        response.setStatus(404)
    else:
        # OK
        response.setStatus(200)
except:
    # Internal Server Error
    response.setStatus(500)

You can find implementation details in the plone.restapi.services.content.add.FolderPost class

GET Responses¶

Possible server reponses for a GET request are:

Updating a Resource with PATCH¶

To update an existing resource we send a PATCH request to the server. PATCH allows to provide just a subset of the resource (the values you actually want to change).

If you send the value null for a field, the field’s content will be deleted and the missing_value defined for the field in the schema will be set. Note that this is not possible if the field is required, and it only works for Dexterity types, not Archetypes:

http

PATCH /plone/folder/my-document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "title": "My New Document Title"
}

curl

curl -i -X PATCH http://nohost/plone/folder/my-document -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"title": "My New Document Title"}' --user admin:secret

httpie

echo '{
  "title": "My New Document Title"
}' | http PATCH http://nohost/plone/folder/my-document Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/folder/my-document', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'title': 'My New Document Title',
}, auth=('admin', 'secret'))

Successful Response (204 No Content)¶

A successful response to a PATCH request will be indicated by a 204 No Content response by default:

HTTP/1.1 204 No Content

Successful Response (200 OK)¶

You can get the object representation by adding a Prefer header with a value of return=representation to the PATCH request. In this case, the response will be a 200 OK:

http

PATCH /plone/folder/my-document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Prefer: return=representation
Content-Type: application/json

{
    "title": "My New Document Title"
}

curl

curl -i -X PATCH http://nohost/plone/folder/my-document -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'Prefer: return=representation' --data-raw '{"title": "My New Document Title"}' --user admin:secret

httpie

echo '{
  "title": "My New Document Title"
}' | http PATCH http://nohost/plone/folder/my-document Accept:application/json Content-Type:application/json Prefer:return=representation -a admin:secret

python-requests

requests.patch('http://nohost/plone/folder/my-document', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Prefer': 'return=representation',
}, json={
    'title': 'My New Document Title',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/folder/my-document/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/folder/my-document/@breadcrumbs"
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/folder/my-document/@navigation"
    }, 
    "types": {
      "@id": "http://localhost:55001/plone/folder/my-document/@types"
    }, 
    "workflow": {
      "@id": "http://localhost:55001/plone/folder/my-document/@workflow"
    }
  }, 
  "@id": "http://localhost:55001/plone/folder/my-document", 
  "@type": "Document", 
  "UID": "SomeUUID000000000000000000000005", 
  "allow_discussion": false, 
  "changeNote": "", 
  "contributors": [], 
  "created": "1995-07-31T13:45:00", 
  "creators": [
    "admin"
  ], 
  "description": "", 
  "effective": null, 
  "exclude_from_nav": false, 
  "expires": null, 
  "id": "my-document", 
  "is_folderish": false, 
  "language": "", 
  "layout": "document_view", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone/folder", 
    "@type": "Folder", 
    "description": "This is a folder with two documents", 
    "review_state": "private", 
    "title": "My Folder"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "table_of_contents": null, 
  "text": null, 
  "title": "My New Document Title", 
  "version": "current", 
  "versioning_enabled": true
}

See for full specs the RFC 5789: PATCH Method for HTTP

Replacing a Resource with PUT¶

Note

PUT is not implemented yet.

To replace an existing resource we send a PUT request to the server:

TODO: Add example.

In accordance with the HTTP specification, a successful PUT will not create a new resource or produce a new URL.

PUT expects the entire resource representation to be supplied to the server, rather than just changes to the resource state. This is usually not a problem since the consumer application requested the resource representation before a PUT anyways.

When the PUT request is accepted and processed by the service, the consumer will receive a 204 No Content response (200 OK would be a valid alternative).

Successful Update (204 No Content)¶

When a resource has been updated successfully, the server sends a 204 No Content response:

TODO: Add example.

Unsuccessful Update (409 Conflict)¶

Sometimes requests fail due to incompatible changes. The response body includes additional information about the problem.

TODO: Add example.

PUT Implementation¶

A pseudo-code example of the PUT implementation on the server:

try:
    order = getOrder()
    if order:
        try:
            saveOrder()
        except conflict:
            response.setStatus(409)
        # OK
        response.setStatus(200)
    else:
        # Not Found
        response.setStatus(404)
except:
    # Internal Server Error
    response.setStatus(500)

TODO: Link to the real implementation…

PUT Responses¶

Possible server reponses for a PUT request are:

POST vs. PUT¶

Difference between POST and PUT:

Use POST to create a resource identified by a service-generated URI

Use POST to append a resource to a collection identified by a service-generated URI

Use PUT to overwrite a resource

This follows RFC 7231: HTTP 1.1: PUT Method.

Removing a Resource with DELETE¶

We can delete an existing resource by sending a DELETE request:

http

DELETE /plone/folder/my-document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X DELETE http://nohost/plone/folder/my-document -H 'Accept: application/json' --user admin:secret

httpie

http DELETE http://nohost/plone/folder/my-document Accept:application/json -a admin:secret

python-requests

requests.delete('http://nohost/plone/folder/my-document', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

A successful response will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content

DELETE Implementation¶

A pseudo-code example of the DELETE implementation on the server:

try:
    order = getOrder()
    if order:
        if can_delete(order):
            # No Content
            response.setStatus(204)
        else:
            # Not Allowed
            response.setStatus(405)
    else:
        # Not Found
        response.setStatus(404)
except:
    # Internal Server Error
    response.setStatus(500)

TODO: Link to the real implementation…

DELETE Responses¶

Possible responses to a delete request are:

204 No Content

404 Not Found (if the resource does not exist)

405 Method Not Allowed (if deleting the resource is not allowed)

500 Internal Server Error

Reordering sub resources¶

The resources contained within a resource can be reordered using the ordering key using a PATCH request on the container.

Use the obj_id subkey to specify which resource to reorder. The subkey delta can be ‘top’, ‘bottom’, or a negative or positive integer for moving up or down.

Reordering resources within a subset of resources can be done using the subset_ids subkey.

A response 400 BadRequest with a message ‘Client/server ordering mismatch’ will be returned if the value is not in the same order as serverside.

A response 400 BadRequest with a message ‘Content ordering is not supported by this resource’ will be returned if the container does not support ordering.

http

PATCH /plone/folder/my-document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "ordering": {"obj_id": "item_3", "delta": "top", "subset_ids": ["item_1", "item_3", "item5"]}
}

curl

curl -i -X PATCH http://nohost/plone/folder/my-document -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"ordering": {"delta": "top", "obj_id": "item_3", "subset_ids": ["item_1", "item_3", "item5"]}}' --user admin:secret

httpie

echo '{
  "ordering": {
    "delta": "top",
    "obj_id": "item_3",
    "subset_ids": [
      "item_1",
      "item_3",
      "item5"
    ]
  }
}' | http PATCH http://nohost/plone/folder/my-document Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/folder/my-document', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'ordering': {
        'delta': 'top',
        'obj_id': 'item_3',
        'subset_ids': ['item_1', 'item_3', 'item5'],
    },
}, auth=('admin', 'secret'))

History¶

The @history endpoint exposes history and versioning information on previous versions of the content. Each change or workflow change on a content object or file is listed. It also allows to revert to a previous version of the file.

Listing the History of a Content Object¶

Listing versions and history of a resource:

http

GET /plone/front-page/@history HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/front-page/@history -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/front-page/@history Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@history', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/front-page/@history/0", 
    "action": "Edited", 
    "actor": {
      "@id": "http://localhost:55001/plone/@users/test-user", 
      "fullname": "test-user", 
      "id": "test-user", 
      "username": null
    }, 
    "comments": "Initial version", 
    "may_revert": true, 
    "time": "1995-07-31T17:30:00", 
    "transition_title": "Edited", 
    "type": "versioning", 
    "version": 0
  }, 
  {
    "action": "Create", 
    "actor": {
      "@id": "http://localhost:55001/plone/@users/test_user_1_", 
      "fullname": "", 
      "id": "test_user_1_", 
      "username": "test-user"
    }, 
    "comments": "", 
    "review_state": "private", 
    "state_title": "Private", 
    "time": "1995-07-31T18:30:00", 
    "transition_title": "Create", 
    "type": "workflow"
  }
]

This following fields are returned:

action: the workflow transition id, ‘Edited’ for versioning, or ‘Create’ for initial state.
actor: the user who performed the action. This contains a subobject with the details.
comments: a changenote
@id: link to the content endpoint of this specific version.
may_revert: true if the user has permission to revert.
time: when this action occured in ISO format.
transition_title: the workflow transition’s title, ‘Edited’ for versioning, or ‘Create’ for initial state.
type: ‘workflow’ for workflow changes, ‘versioning’ for editing, or null for content creation.
version: identifier for this specific version of the resource.

Get a Historical Version¶

Older versions of a resource can be retrieved by appending version to the @history endpoint url.

http

GET /plone/folder/my-document/@history/0 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/folder/my-document/@history/0 -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/folder/my-document/@history/0 Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/folder/my-document/@history/0', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Revert to a Historical Version¶

Reverting to an older versions of a resource can be done by sending a PATCH request to the @history endpoint and appending the version you want to revert to.

http

PATCH /plone/front-page/@history HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "version": 0
}

curl

curl -i -X PATCH http://nohost/plone/front-page/@history -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"version": 0}' --user admin:secret

httpie

echo '{
  "version": 0
}' | http PATCH http://nohost/plone/front-page/@history Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/front-page/@history', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'version': 0,
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Welcome to Plone has been reverted to revision 0."
}

Batching¶

Representations of collection-like resources are batched / paginated if the size of the resulset exceeds the batching size:

{
  "@id": "http://.../folder/search",
  "batching": {
    "@id": "http://.../folder/search?b_size=10&b_start=20",
    "first": "http://.../plone/folder/search?b_size=10&b_start=0",
    "last": "http://.../plone/folder/search?b_size=10&b_start=170",
    "prev": "http://.../plone/folder/search?b_size=10&b_start=10",
    "next": "http://.../plone/folder/search?b_size=10&b_start=30"
  },
  "items": [
    "..."
  ],
  "items_total": 175,
}

If the entire resulset fits into a single batch page (as determined by b_size), the top-level batching links will be omitted.

Top-level attributes¶

Attribute	Description
`@id`	Canonical base URL for the resource, without any batching parameters
`items`	Current batch of items / members of the collection-like resource
`items_total`	Total number of items
`batching`	Batching related navigation links (see below)

Batching links¶

If, and only if, the resultset has been batched over several pages, the response body will contain a top-level attribute batching that contains batching links. These links that can be used to navigate batches in a Hypermedia fashion:

Attribute	Description
`@id`	Link to the current batch page
`first`	Link to the first batch page
`prev`	Link to the previous batch page (if applicable)
`next`	Link to the next batch page (if applicable)
`last`	Link to the last batch page

Parameters¶

Batching can be controlled with two query string parameters. In order to address a specific batch page, the b_start parameter can be used to request a specific batch page, containing b_size items starting from b_start.

Parameter	Description
`b_size`	Batch size (default is 25)
`b_start`	First item of the batch

Full example of a batched request and response:

http

GET /plone/folder/@search?b_size=5&sort_on=path HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/folder/@search?b_size=5&sort_on=path' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/folder/@search?b_size=5&sort_on=path' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/folder/@search?b_size=5&sort_on=path', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/folder/@search", 
  "batching": {
    "@id": "http://localhost:55001/plone/folder/@search?b_size=5&sort_on=path", 
    "first": "http://localhost:55001/plone/folder/@search?b_start=0&b_size=5&sort_on=path", 
    "last": "http://localhost:55001/plone/folder/@search?b_start=5&b_size=5&sort_on=path", 
    "next": "http://localhost:55001/plone/folder/@search?b_start=5&b_size=5&sort_on=path"
  }, 
  "items": [
    {
      "@id": "http://localhost:55001/plone/folder", 
      "@type": "Folder", 
      "description": "", 
      "review_state": "private", 
      "title": "Folder"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder/doc-1", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "Document 1"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder/doc-2", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "Document 2"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder/doc-3", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "Document 3"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder/doc-4", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "Document 4"
    }
  ], 
  "items_total": 8
}

Comments¶

Plone offers users to post comments on any content object with plone.app.discussion.

Commenting can be enabled globally, for specific content types and for single content objects.

When commenting is enabled on your content object, you can retrieve a list of all existing comments, add new comments, reply to existing comments or delete a comment.

Listing Comments¶

You can list the existing comment on a content object by sending a GET request to the URL of the content object and appending ‘/@comments’:

http

GET /plone/front-page/@comments HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/front-page/@comments -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/front-page/@comments Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@comments', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a Status 200 and a batched list of all comments:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/front-page/@comments", 
  "items": [
    {
      "@id": "http://localhost:55001/plone/front-page/@comments/1400000000000000", 
      "@parent": null, 
      "@type": "Discussion Item", 
      "author_name": null, 
      "author_username": null, 
      "comment_id": "1400000000000000", 
      "creation_date": "1995-07-31T13:45:00", 
      "in_reply_to": null, 
      "is_deletable": true, 
      "is_editable": true, 
      "modification_date": "1995-07-31T17:30:00", 
      "text": {
        "data": "Comment 1", 
        "mime-type": "text/plain"
      }, 
      "user_notification": null
    }, 
    {
      "@id": "http://localhost:55001/plone/front-page/@comments/1400000000000001", 
      "@parent": "http://localhost:55001/plone/front-page/@comments/1400000000000000", 
      "@type": "Discussion Item", 
      "author_name": null, 
      "author_username": null, 
      "comment_id": "1400000000000001", 
      "creation_date": "1995-07-31T13:45:00", 
      "in_reply_to": "1400000000000000", 
      "is_deletable": true, 
      "is_editable": true, 
      "modification_date": "1995-07-31T17:30:00", 
      "text": {
        "data": "Comment 1.1", 
        "mime-type": "text/plain"
      }, 
      "user_notification": null
    }
  ], 
  "items_total": 2
}

These following fields are returned:

@id: Link to the current endpoint
items: a list of comments for the current resource
items_total: the total number of comments for the resource
batching: batching information

The items attribute returns a list of comments, each comment provides the following fields:

@id: hyperlink to the comment
@parent: (optional) the parent comment
author_name: the full name of the author of this comment
author_username: the username of the author of this comment
comment_id: the comment ID uniquely identifies the comment
in_reply_to: the comment ID of the parent comment
creation_date: when the comment was placed
modification_date: when the comment was last updated
text: contains a ‘mime-type’ and ‘text’ attribute with the text of the comment. Default mime-type is ‘text/plain’.
user_notification: boolean value to indicate if the author of the comment requested notifications on replies

Adding a Comment¶

To add a new comment to a content object, send a POST request to the URL of the content object and append ‘/@comments’ to the URL. The body of the request needs to contain a JSON structure with a ‘text’ attribute that contains the comment text:

http

POST /plone/front-page/@comments/ HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "text": "My comment"
}

curl

curl -i -X POST http://nohost/plone/front-page/@comments/ -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"text": "My comment"}' --user admin:secret

httpie

echo '{
  "text": "My comment"
}' | http POST http://nohost/plone/front-page/@comments/ Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/front-page/@comments/', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'text': 'My comment',
}, auth=('admin', 'secret'))

If the creation of the comment has been successful, the server will respond with a 204 No Content status and the URL of the newly created comment in the location header:

HTTP/1.1 204 No Content
Location: http://localhost:55001/plone/front-page/@comments/123456

Replying to a Comment¶

To add a direct reply to an existing comment, send a POST request to the URL of the comment you want to reply to. The body of the request needs to contain a JSON structure with a ‘text’ attribute that contains the comment text:

http

POST /plone/front-page/@comments/123456 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "text": "My reply"
}

curl

curl -i -X POST http://nohost/plone/front-page/@comments/123456 -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"text": "My reply"}' --user admin:secret

httpie

echo '{
  "text": "My reply"
}' | http POST http://nohost/plone/front-page/@comments/123456 Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/front-page/@comments/123456', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'text': 'My reply',
}, auth=('admin', 'secret'))

If the creation of the comment has been successful, the server will respond with a 204 No Content status and the URL of the newly created comment in the location header:

HTTP/1.1 204 No Content
Location: http://localhost:55001/plone/front-page/@comments/123456

Updating a Comment¶

..note: The permission to update a comment is, by default, only granted to the creater (owner role) of the comment.

An existing comment can be updated by sending a PATCH request to the URL of the comment. The request body needs to contain a JSON structure with at least a ‘text’ attribute:

http

PATCH /plone/front-page/@comments/123456 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "text": "My NEW comment"
}

curl

curl -i -X PATCH http://nohost/plone/front-page/@comments/123456 -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"text": "My NEW comment"}' --user admin:secret

httpie

echo '{
  "text": "My NEW comment"
}' | http PATCH http://nohost/plone/front-page/@comments/123456 Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/front-page/@comments/123456', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'text': 'My NEW comment',
}, auth=('admin', 'secret'))

The server will respond with a 204 No Content response and a location header with the comment URL when the comment has been updated successfully:

HTTP/1.1 204 No Content
Location: http://localhost:55001/plone/front-page/@comments/123456

Deleting a Comment¶

An existing comment can be deleted by sending a DELETE request to the URL of the comment.

..note: Deleting a comment will, by default, also delete all existing replies to that comment.

http

DELETE /plone/front-page/@comments/123456 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X DELETE http://nohost/plone/front-page/@comments/123456 -H 'Accept: application/json' --user admin:secret

httpie

http DELETE http://nohost/plone/front-page/@comments/123456 Accept:application/json -a admin:secret

python-requests

requests.delete('http://nohost/plone/front-page/@comments/123456', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

When the comment has been deleted successfully, the server will respond with a 204 No Content response:

HTTP/1.1 204 No Content

Copy / Move¶

Copying an object¶

To copy a content object send a POST request to the /@copy endpoint at the destinations url with the source object specified in the request body. The source object can be specified either by url, path, UID or intid.

http

POST /plone/@copy HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "source": "http://localhost:55001/plone/front-page"
}

curl

curl -i -X POST http://nohost/plone/@copy -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"source": "http://localhost:55001/plone/front-page"}' --user admin:secret

httpie

echo '{
  "source": "http://localhost:55001/plone/front-page"
}' | http POST http://nohost/plone/@copy Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@copy', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'source': 'http://localhost:55001/plone/front-page',
}, auth=('admin', 'secret'))

If the copy operation succeeds, the server will respond with status 200 (OK) and return the new and old url of the copied object.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "source": "http://localhost:55001/plone/front-page", 
    "target": "http://localhost:55001/plone/copy_of_front-page"
  }
]

Moving an object¶

To move a content object send a POST request to the /@move endpoint at the destinations url with the source object specified in the request body. The source object can be specified either by url, path, UID or intid.

http

POST /plone/folder/@move HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "source": "http://localhost:55001/plone/front-page"
}

curl

curl -i -X POST http://nohost/plone/folder/@move -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"source": "http://localhost:55001/plone/front-page"}' --user admin:secret

httpie

echo '{
  "source": "http://localhost:55001/plone/front-page"
}' | http POST http://nohost/plone/folder/@move Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/folder/@move', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'source': 'http://localhost:55001/plone/front-page',
}, auth=('admin', 'secret'))

If the move operation succeeds, the server will respond with status 200 (OK) and return the new and old url of the moved object.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "source": "http://localhost:55001/plone/front-page", 
    "target": "http://localhost:55001/plone/folder/front-page"
  }
]

Copying/moving multiple objects¶

Multiple objects can be moved/copied by giving a list of sources.

http

POST /plone/@copy HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "source": [
        "http://localhost:55001/plone/front-page",
        "http://localhost:55001/plone/newsitem"
    ]
}

curl

curl -i -X POST http://nohost/plone/@copy -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"source": ["http://localhost:55001/plone/front-page", "http://localhost:55001/plone/newsitem"]}' --user admin:secret

httpie

echo '{
  "source": [
    "http://localhost:55001/plone/front-page",
    "http://localhost:55001/plone/newsitem"
  ]
}' | http POST http://nohost/plone/@copy Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@copy', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'source': ['http://localhost:55001/plone/front-page', 'http://localhost:55001/plone/newsitem'],
}, auth=('admin', 'secret'))

If the operation succeeds, the server will respond with status 200 (OK) and return the new and old urls for each copied/moved object.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "source": "http://localhost:55001/plone/front-page", 
    "target": "http://localhost:55001/plone/copy_of_front-page"
  }, 
  {
    "source": "http://localhost:55001/plone/newsitem", 
    "target": "http://localhost:55001/plone/copy_of_newsitem"
  }
]

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” within the document GET request.

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": [
      {"@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"},
      ...
  },
  "UID": "1f699ffa110e45afb1ba502f75f7ec33",
  "title": "Welcome to Plone",
  ...
}

Request (unexpanded):

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'))

Response (unexpanded):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@components": {
    "actions": {
      "@id": "http://localhost:55001/plone/front-page/@actions"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/front-page/@breadcrumbs"
    }, 
    "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", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "table_of_contents": null, 
  "text": {
    "content-type": "text/plain", 
    "data": "<p>If you&#x27;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", 
  "versioning_enabled": true
}

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 component:

http

GET /plone/front-page?expand=breadcrumbs HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i '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"
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/front-page/@breadcrumbs", 
      "items": [
        {
          "@id": "http://localhost:55001/plone/front-page", 
          "title": "Welcome to Plone"
        }
      ]
    }, 
    "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", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "table_of_contents": null, 
  "text": {
    "content-type": "text/plain", 
    "data": "<p>If you&#x27;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", 
  "versioning_enabled": true
}

Here is an exaxmple 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 '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": "", 
          "id": "view", 
          "title": "View"
        }, 
        {
          "icon": "", 
          "id": "edit", 
          "title": "Edit"
        }, 
        {
          "icon": "", 
          "id": "folderContents", 
          "title": "Contents"
        }, 
        {
          "icon": "", 
          "id": "history", 
          "title": "History"
        }, 
        {
          "icon": "", 
          "id": "local_roles", 
          "title": "Sharing"
        }
      ], 
      "object_buttons": [
        {
          "icon": "", 
          "id": "cut", 
          "title": "Cut"
        }, 
        {
          "icon": "", 
          "id": "copy", 
          "title": "Copy"
        }, 
        {
          "icon": "", 
          "id": "delete", 
          "title": "Delete"
        }, 
        {
          "icon": "", 
          "id": "rename", 
          "title": "Rename"
        }, 
        {
          "icon": "", 
          "id": "redirection", 
          "title": "URL Management"
        }
      ], 
      "portal_tabs": [
        {
          "icon": "", 
          "id": "index_html", 
          "title": "Home"
        }
      ], 
      "site_actions": [
        {
          "icon": "", 
          "id": "sitemap", 
          "title": "Site Map"
        }, 
        {
          "icon": "", 
          "id": "accessibility", 
          "title": "Accessibility"
        }, 
        {
          "icon": "", 
          "id": "contact", 
          "title": "Contact"
        }
      ], 
      "user": [
        {
          "icon": "", 
          "id": "preferences", 
          "title": "Preferences"
        }, 
        {
          "icon": "", 
          "id": "dashboard", 
          "title": "Dashboard"
        }, 
        {
          "icon": "", 
          "id": "plone_setup", 
          "title": "Site Setup"
        }, 
        {
          "icon": "", 
          "id": "logout", 
          "title": "Log out"
        }
      ]
    }, 
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/front-page/@breadcrumbs", 
      "items": [
        {
          "@id": "http://localhost:55001/plone/front-page", 
          "title": "Welcome to Plone"
        }
      ]
    }, 
    "navigation": {
      "@id": "http://localhost:55001/plone/front-page/@navigation", 
      "items": [
        {
          "@id": "http://localhost:55001/plone", 
          "description": "", 
          "title": "Home"
        }, 
        {
          "@id": "http://localhost:55001/plone/front-page", 
          "description": "Congratulations! You have successfully installed Plone.", 
          "title": "Welcome to Plone"
        }
      ]
    }, 
    "types": [
      {
        "@id": "http://localhost:55001/plone/@types/Collection", 
        "addable": false, 
        "title": "Collection"
      }, 
      {
        "@id": "http://localhost:55001/plone/@types/DXTestDocument", 
        "addable": false, 
        "title": "DX Test Document"
      }, 
      {
        "@id": "http://localhost:55001/plone/@types/Event", 
        "addable": false, 
        "title": "Event"
      }, 
      {
        "@id": "http://localhost:55001/plone/@types/File", 
        "addable": false, 
        "title": "File"
      }, 
      {
        "@id": "http://localhost:55001/plone/@types/Folder", 
        "addable": false, 
        "title": "Folder"
      }, 
      {
        "@id": "http://localhost:55001/plone/@types/Image", 
        "addable": false, 
        "title": "Image"
      }, 
      {
        "@id": "http://localhost:55001/plone/@types/Link", 
        "addable": false, 
        "title": "Link"
      }, 
      {
        "@id": "http://localhost:55001/plone/@types/News Item", 
        "addable": false, 
        "title": "News Item"
      }, 
      {
        "@id": "http://localhost:55001/plone/@types/Document", 
        "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", 
          "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", 
  "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", 
  "modified": "1995-07-31T17:30:00", 
  "parent": {
    "@id": "http://localhost:55001/plone", 
    "@type": "Plone Site", 
    "description": "", 
    "title": "Plone site"
  }, 
  "relatedItems": [], 
  "review_state": "private", 
  "rights": "", 
  "subjects": [], 
  "table_of_contents": null, 
  "text": {
    "content-type": "text/plain", 
    "data": "<p>If you&#x27;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", 
  "versioning_enabled": true
}

Portal Actions¶

Plone has the concept of configurable actions (called “portal_actions”). Each actions defines an id, a title, the required permissions and a condition that will be checked to decide if the action will be available for a user. Actions are sorted by categories.

Actions can be used to build UI elements that adapt to the available actions. An example is the Plone toolbar where the “object_tabs” (view, edit, folder contents, sharing) and the “user_actions” (login, logout, preferences) are used to display the user only the actions that are allowed for the currently logged in user.

The available actions for the currently logged in user can be retrieved by calling the @actions endpoint on a specific context. This also works for not authenticated users.

Listing available actions¶

To list the available actions, send a GET request to the ‘@actions’ endpoint on a specific content object:

http

GET /plone/@actions HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@actions -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@actions Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@actions', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a 200 OK status code. The JSON response contains the available actions categories (object, object_buttons, user) on the top level. Each category contains a list of the available actions in that category:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "object": [
    {
      "icon": "", 
      "id": "view", 
      "title": "View"
    }, 
    {
      "icon": "", 
      "id": "edit", 
      "title": "Edit"
    }, 
    {
      "icon": "", 
      "id": "folderContents", 
      "title": "Contents"
    }, 
    {
      "icon": "", 
      "id": "history", 
      "title": "History"
    }, 
    {
      "icon": "", 
      "id": "local_roles", 
      "title": "Sharing"
    }
  ], 
  "object_buttons": [
    {
      "icon": "", 
      "id": "cut", 
      "title": "Cut"
    }, 
    {
      "icon": "", 
      "id": "copy", 
      "title": "Copy"
    }, 
    {
      "icon": "", 
      "id": "delete", 
      "title": "Delete"
    }, 
    {
      "icon": "", 
      "id": "rename", 
      "title": "Rename"
    }
  ], 
  "user": [
    {
      "icon": "", 
      "id": "preferences", 
      "title": "Preferences"
    }, 
    {
      "icon": "", 
      "id": "plone_setup", 
      "title": "Site Setup"
    }, 
    {
      "icon": "", 
      "id": "logout", 
      "title": "Log out"
    }
  ]
}

If you want to limit the categories that are retured, pass one or more parameters categories:list, i.e. @action?categories:list=object&categories:list=user.

Workflow¶

Note

Currently the workflow support is limited to executing transitions on content.

In Plone, content almost always has a workflow attached. We can get the current state and history of an object by issuing a GET request using on any context:

http

GET /plone/front-page/@workflow HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/front-page/@workflow -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/front-page/@workflow Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@workflow', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@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", 
      "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"
    }
  ]
}

Now, if we want to change the state of the front page to publish, we would proceed by issuing a POST request to the given URL:

http

POST /plone/front-page/@workflow/publish HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X POST http://nohost/plone/front-page/@workflow/publish -H 'Accept: application/json' --user admin:secret

httpie

http POST http://nohost/plone/front-page/@workflow/publish Accept:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/front-page/@workflow/publish', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "action": "publish", 
  "actor": "admin", 
  "comments": "", 
  "review_state": "published", 
  "time": "1995-07-31T18:30:00", 
  "title": "Published with accent \u00e9"
}

We can also also change the state recursively for all contained items, provide a comment and set effective and expiration dates:

http

POST /plone/folder/@workflow/publish HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "comment": "Publishing my folder...",
    "effective": "2018-01-21T08:00:00",
    "expires": "2019-01-21T08:00:00",
    "include_children": true
}

curl

curl -i -X POST http://nohost/plone/folder/@workflow/publish -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"comment": "Publishing my folder...", "effective": "2018-01-21T08:00:00", "expires": "2019-01-21T08:00:00", "include_children": true}' --user admin:secret

httpie

echo '{
  "comment": "Publishing my folder...",
  "effective": "2018-01-21T08:00:00",
  "expires": "2019-01-21T08:00:00",
  "include_children": true
}' | http POST http://nohost/plone/folder/@workflow/publish Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/folder/@workflow/publish', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'comment': 'Publishing my folder...',
    'effective': '2018-01-21T08:00:00',
    'expires': '2019-01-21T08:00:00',
    'include_children': True,
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "action": "publish", 
  "actor": "admin", 
  "comments": "Publishing my folder...", 
  "review_state": "published", 
  "time": "1995-07-31T18:30:00", 
  "title": "Published with accent \u00e9"
}

Locking¶

Locking is a mechanism to prevent users from accidentially overriding each others changes.

When a user edits a content object in Plone, the object is locked until the user hits the save or cancel button. If a second user tries to edit the object at the same time, she will see a message that this object is locked.

Locking an object¶

To lock an object send a POST request to the /@lock endpoint that is available on any content object in Plone:

http

POST /plone/front-page/@lock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X POST http://nohost/plone/front-page/@lock -H 'Accept: application/json' --user admin:secret

httpie

http POST http://nohost/plone/front-page/@lock Accept:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/front-page/@lock', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

If the lock operation succeeds, the server will respond with status 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.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "creator": "admin", 
  "locked": true, 
  "name": "plone.locking.stealable", 
  "stealable": true, 
  "time": 807211800.0, 
  "timeout": 600, 
  "token": "0.684672730996-0.25195226375-00105A989226:1477076400.000"
}

By default, locks are stealable. That means that another user can unlock the object. If you want to create a non-stealable lock, pass "stealable": false in the request body.

To create a lock with a non-default timeout, you can pass the the timeout value in seconds in the request body.

The following example creates a non-stealable lock with a timeout of 1h.

http

POST /plone/front-page/@lock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "stealable": false,
    "timeout": 3600
}

curl

curl -i -X POST http://nohost/plone/front-page/@lock -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"stealable": false, "timeout": 3600}' --user admin:secret

httpie

echo '{
  "stealable": false,
  "timeout": 3600
}' | http POST http://nohost/plone/front-page/@lock Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/front-page/@lock', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'stealable': False,
    'timeout': 3600,
}, auth=('admin', 'secret'))

The server responds with status 200 OK and returns the lock information.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "creator": "admin", 
  "locked": true, 
  "name": "plone.locking.stealable", 
  "stealable": true, 
  "time": 807211800.0, 
  "timeout": 3600, 
  "token": "0.684672730996-0.25195226375-00105A989226:1477076400.000"
}

Unlocking an object¶

To unlock an object send a POST request to the /@unlock endpoint.

http

POST /plone/front-page/@unlock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X POST http://nohost/plone/front-page/@unlock -H 'Accept: application/json' --user admin:secret

httpie

http POST http://nohost/plone/front-page/@unlock Accept:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/front-page/@unlock', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server responds with status 200 OK and returns the lock information.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "locked": false, 
  "stealable": true
}

Refreshing a lock¶

An existing lock can be refreshed by sending a POST request to the @refresh-lock endpoint.

http

POST /plone/front-page/@refresh-lock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X POST http://nohost/plone/front-page/@refresh-lock -H 'Accept: application/json' --user admin:secret

httpie

http POST http://nohost/plone/front-page/@refresh-lock Accept:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/front-page/@refresh-lock', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server responds with status 200 OK and returns the lock information containing the updated creation time.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "creator": "admin", 
  "locked": true, 
  "name": "plone.locking.stealable", 
  "stealable": true, 
  "time": 807211800.0, 
  "timeout": 600, 
  "token": "0.684672730996-0.25195226375-00105A989226:1477076400.000"
}

Getting lock information¶

To find out if an object is locked or to get information about the current lock you can send a GET request to the @lock endpoint.

http

GET /plone/front-page/@lock HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/front-page/@lock -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/front-page/@lock Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@lock', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server responds with status 200 OK and returns the information about the lock.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "locked": false, 
  "stealable": true
}

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

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"
}

curl

curl -i -X PATCH http://nohost/plone/front-page -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'Lock-Token: 0.684672730996-0.25195226375-00105A989226:1477076400.000' --data-raw '{"title": "New Title"}' --user admin:secret

httpie

echo '{
  "title": "New Title"
}' | http PATCH http://nohost/plone/front-page Accept:application/json Content-Type:application/json Lock-Token:0.684672730996-0.25195226375-00105A989226:1477076400.000 -a admin:secret

python-requests

requests.patch('http://nohost/plone/front-page', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Lock-Token': '0.684672730996-0.25195226375-00105A989226:1477076400.000',
}, json={
    'title': 'New Title',
}, auth=('admin', 'secret'))

Registry¶

Registry records can be addressed through the @registry endpoint on the Plone site. In order to address a specific record, the fully qualified dotted name of the registry record has to be passed as a path segment (e.g. /plone/@registy/my.record).

Reading or writing registry records require the cmf.ManagePortal permission.

Reading registry records¶

Reading a single record:

http

GET /plone/@registry/plone.app.querystring.field.path.title HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@registry/plone.app.querystring.field.path.title -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@registry/plone.app.querystring.field.path.title Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@registry/plone.app.querystring.field.path.title', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

"Location"

Listing registry records¶

The registry records listing uses a batched method to access all registry records. See Batching for more details on how to work with batched results.

The output per record contains the following fields: name: The record’s fully qualified dotted name. value: The record’s value. This is the same as GETting @registry/name.

http

GET /plone/@registry HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@registry -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@registry Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@registry', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@registry", 
  "batching": {
    "@id": "http://localhost:55001/plone/@registry", 
    "first": "http://localhost:55001/plone/@registry?b_start=0", 
    "last": "http://localhost:55001/plone/@registry?b_start=1675", 
    "next": "http://localhost:55001/plone/@registry?b_start=25"
  }, 
  "items": [
    {
      "name": "Products.CMFPlone.i18nl10n.override_dateformat.Enabled", 
      "schema": {
        "properties": {
          "description": "Override the translation machinery", 
          "title": "Enabled", 
          "type": "boolean"
        }
      }, 
      "value": false
    }, 
    {
      "name": "Products.CMFPlone.i18nl10n.override_dateformat.date_format_long", 
      "schema": {
        "properties": {
          "description": "Default value: %Y-%m-%d %H:%M (2038-01-19 03:14)", 
          "title": "old ZMI property: localLongTimeFormat", 
          "type": "string"
        }
      }, 
      "value": "%Y-%m-%d %H:%M"
    }, 
    {
      "name": "Products.CMFPlone.i18nl10n.override_dateformat.date_format_short", 
      "schema": {
        "properties": {
          "description": "Default value: %Y-%m-%d (2038-01-19)", 
          "title": "old ZMI property: localTimeFormat", 
          "type": "string"
        }
      }, 
      "value": "%Y-%m-%d"
    }, 
    {
      "name": "Products.CMFPlone.i18nl10n.override_dateformat.time_format", 
      "schema": {
        "properties": {
          "description": "Default value: %H:%M (03:14)", 
          "title": "old ZMI property: localTimeOnlyFormat", 
          "type": "string"
        }
      }, 
      "value": "%H:%M"
    }, 
    {
      "name": "Products.CMFPlone.interfaces.syndication.ISiteSyndicationSettings.allowed", 
      "schema": {
        "properties": {
          "default": true, 
          "description": "Allow syndication for collections and folders on site.", 
          "title": "Allowed", 
          "type": "boolean"
        }
      }, 
      "value": true
    }, 
    {
      "name": "Products.CMFPlone.interfaces.syndication.ISiteSyndicationSettings.allowed_feed_types", 
      "schema": {
        "properties": {
          "additionalItems": true, 
          "default": [
            "RSS|RSS 1.0", 
            "rss.xml|RSS 2.0", 
            "atom.xml|Atom", 
            "itunes.xml|iTunes"
          ], 
          "description": "Separate view name and title by '|'", 
          "items": {
            "description": "", 
            "title": "", 
            "type": "string"
          }, 
          "title": "Allowed Feed Types", 
          "type": "array", 
          "uniqueItems": true
        }
      }, 
      "value": [
        "RSS|RSS 1.0", 
        "rss.xml|RSS 2.0", 
        "atom.xml|Atom", 
        "itunes.xml|iTunes"
      ]
    }, 
    {
      "name": "Products.CMFPlone.interfaces.syndication.ISiteSyndicationSettings.default_enabled", 
      "schema": {
        "properties": {
          "default": false, 
          "description": "If syndication should be enabled by default for all folders and collections.", 
          "title": "Enabled by default", 
          "type": "boolean"
        }
      }, 
      "value": false
    }, 
    {
      "name": "Products.CMFPlone.interfaces.syndication.ISiteSyndicationSettings.max_items", 
      "schema": {
        "properties": {
          "default": 15, 
          "description": "Maximum number of items that will be syndicated.", 
          "minimum": 1, 
          "title": "Maximum items", 
          "type": "integer"
        }
      }, 
      "value": 15
    }, 
    {
      "name": "Products.CMFPlone.interfaces.syndication.ISiteSyndicationSettings.render_body", 
      "schema": {
        "properties": {
          "default": false, 
          "description": "If body text available for item, render it, otherwise use description.", 
          "title": "Render Body", 
          "type": "boolean"
        }
      }, 
      "value": false
    }, 
    {
      "name": "Products.CMFPlone.interfaces.syndication.ISiteSyndicationSettings.search_rss_enabled", 
      "schema": {
        "properties": {
          "default": true, 
          "description": "Allows users to subscribe to feeds of search results", 
          "title": "Search RSS enabled", 
          "type": "boolean"
        }
      }, 
      "value": true
    }, 
    {
      "name": "Products.CMFPlone.interfaces.syndication.ISiteSyndicationSettings.show_author_info", 
      "schema": {
        "properties": {
          "default": true, 
          "description": "Should feeds include author information", 
          "title": "Show author info", 
          "type": "boolean"
        }
      }, 
      "value": true
    }, 
    {
      "name": "Products.CMFPlone.interfaces.syndication.ISiteSyndicationSettings.show_syndication_button", 
      "schema": {
        "properties": {
          "description": "Makes it possible to customize syndication settings for particular folders and collections ", 
          "title": "Show settings button", 
          "type": "boolean"
        }
      }, 
      "value": null
    }, 
    {
      "name": "Products.CMFPlone.interfaces.syndication.ISiteSyndicationSettings.show_syndication_link", 
      "schema": {
        "properties": {
          "description": "Enable RSS link document action on the syndication content item.", 
          "title": "Show feed link", 
          "type": "boolean"
        }
      }, 
      "value": null
    }, 
    {
      "name": "Products.CMFPlone.interfaces.syndication.ISiteSyndicationSettings.site_rss_items", 
      "schema": {
        "properties": {
          "additionalItems": true, 
          "default": [
            "/news/aggregator"
          ], 
          "description": "Paths to folders and collections to link to at the portal root.", 
          "items": {
            "description": "", 
            "title": "", 
            "type": "string", 
            "vocabulary": {
              "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.SyndicatableFeedItems"
            }
          }, 
          "title": "Site RSS", 
          "type": "array", 
          "uniqueItems": true
        }
      }, 
      "value": [
        "/news/aggregator"
      ]
    }, 
    {
      "name": "plone.alignment_styles", 
      "schema": {
        "properties": {
          "additionalItems": true, 
          "default": [
            "Left|alignleft|alignleft", 
            "Center|aligncenter|aligncenter", 
            "Right|alignright|alignright", 
            "Justify|alignjustify|alignjustify"
          ], 
          "description": "Name|format|icon", 
          "items": {
            "description": "", 
            "title": "", 
            "type": "string"
          }, 
          "title": "Alignment styles", 
          "type": "array", 
          "uniqueItems": false
        }
      }, 
      "value": [
        "Left|alignleft|alignleft", 
        "Center|aligncenter|aligncenter", 
        "Right|alignright|alignright", 
        "Justify|alignjustify|alignjustify"
      ]
    }, 
    {
      "name": "plone.allow_anon_views_about", 
      "schema": {
        "properties": {
          "default": false, 
          "description": "If not selected only logged-in users will be able to view information about who created an item and when it was modified.", 
          "title": "Allow anyone to view 'about' information", 
          "type": "boolean"
        }
      }, 
      "value": false
    }, 
    {
      "name": "plone.allow_external_login_sites", 
      "schema": {
        "properties": {
          "additionalItems": true, 
          "default": [], 
          "description": "", 
          "items": {
            "description": "", 
            "title": "", 
            "type": "string"
          }, 
          "title": "Allow external login sites", 
          "type": "array", 
          "uniqueItems": true
        }
      }, 
      "value": []
    }, 
    {
      "name": "plone.allowed_sizes", 
      "schema": {
        "properties": {
          "additionalItems": true, 
          "default": [
            "large 768:768", 
            "preview 400:400", 
            "mini 200:200", 
            "thumb 128:128", 
            "tile 64:64", 
            "icon 32:32", 
            "listing 16:16"
          ], 
          "description": "Specify all allowed maximum image dimensions, one per line. The required format is &lt;name&gt; &lt;width&gt;:&lt;height&gt;.", 
          "items": {
            "description": "", 
            "title": "", 
            "type": "string"
          }, 
          "title": "Allowed image sizes", 
          "type": "array", 
          "uniqueItems": false
        }
      }, 
      "value": [
        "large 768:768", 
        "preview 400:400", 
        "mini 200:200", 
        "thumb 128:128", 
        "tile 64:64", 
        "icon 32:32", 
        "listing 16:16"
      ]
    }, 
    {
      "name": "plone.allowed_types", 
      "schema": {
        "properties": {
          "additionalItems": true, 
          "default": [
            "text/html", 
            "text/x-web-textile"
          ], 
          "description": "Select which formats are available for users as alternative to the default format. Note that if new formats are installed, they will be enabled for text fields by default unless explicitly turned off here or by the relevant installer.", 
          "items": {
            "description": "", 
            "title": "", 
            "type": "string", 
            "vocabulary": {
              "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AllowableContentTypes"
            }
          }, 
          "title": "Alternative formats", 
          "type": "array", 
          "uniqueItems": true
        }
      }, 
      "value": [
        "text/html", 
        "text/x-web-textile"
      ]
    }, 
    {
      "name": "plone.always_show_selector", 
      "schema": {
        "properties": {
          "default": false, 
          "description": "", 
          "title": "Always show language selector", 
          "type": "boolean"
        }
      }, 
      "value": false
    }, 
    {
      "name": "plone.app.discussion.interfaces.IDiscussionSettings.anonymous_comments", 
      "schema": {
        "properties": {
          "default": false, 
          "description": "If selected, anonymous users are able to post comments without logging in. It is highly recommended to use a captcha solution to prevent spam if this setting is enabled.", 
          "title": "Enable anonymous comments", 
          "type": "boolean"
        }
      }, 
      "value": false
    }, 
    {
      "name": "plone.app.discussion.interfaces.IDiscussionSettings.anonymous_email_enabled", 
      "schema": {
        "properties": {
          "default": false, 
          "description": "If selected, anonymous user will have to give their email.", 
          "title": "Enable anonymous email field", 
          "type": "boolean"
        }
      }, 
      "value": false
    }, 
    {
      "name": "plone.app.discussion.interfaces.IDiscussionSettings.captcha", 
      "schema": {
        "properties": {
          "default": "disabled", 
          "description": "Use this setting to enable or disable Captcha validation for comments. Install plone.formwidget.captcha, plone.formwidget.recaptcha, collective.akismet, or collective.z3cform.norobots if there are no options available.", 
          "title": "Captcha", 
          "type": "string", 
          "vocabulary": {
            "@id": "http://localhost:55001/plone/@vocabularies/plone.app.discussion.vocabularies.CaptchaVocabulary"
          }
        }
      }, 
      "value": "disabled"
    }, 
    {
      "name": "plone.app.discussion.interfaces.IDiscussionSettings.delete_own_comment_enabled", 
      "schema": {
        "properties": {
          "default": false, 
          "description": "If selected, supports deleting of own comments for users with the \"Delete own comments\" permission.", 
          "title": "Enable deleting own comments", 
          "type": "boolean"
        }
      }, 
      "value": false
    }, 
    {
      "name": "plone.app.discussion.interfaces.IDiscussionSettings.edit_comment_enabled", 
      "schema": {
        "properties": {
          "default": false, 
          "description": "If selected, supports editing of comments for users with the \"Edit comments\" permission.", 
          "title": "Enable editing of comments", 
          "type": "boolean"
        }
      }, 
      "value": false
    }
  ], 
  "items_total": 1686
}

Updating registry records¶

Updating an existing record:

http

PATCH /plone/@registry/ HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "plone.app.querystring.field.path.title": "Value"
}

curl

curl -i -X PATCH http://nohost/plone/@registry/ -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"plone.app.querystring.field.path.title": "Value"}' --user admin:secret

httpie

echo '{
  "plone.app.querystring.field.path.title": "Value"
}' | http PATCH http://nohost/plone/@registry/ Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/@registry/', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'plone.app.querystring.field.path.title': 'Value',
}, auth=('admin', 'secret'))

Example Response:

HTTP/1.1 204 No Content

Types¶

Note

These docs are generated by code tests, therefore you will see some ‘test’ contenttypes appear here.

Available content types in a Plone site can be listed and queried by accessing the /@types endpoint on any context (requires an authenticated user). The ‘addable’ key specifies if the content type can be added to the current context. The ‘layouts’ key specifies the defined views.

http

GET /plone/@types HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@types -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@types Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@types', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@types/Collection", 
    "addable": true, 
    "title": "Collection"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/DXTestDocument", 
    "addable": true, 
    "title": "DX Test Document"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Event", 
    "addable": true, 
    "title": "Event"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/File", 
    "addable": true, 
    "title": "File"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Folder", 
    "addable": true, 
    "title": "Folder"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Image", 
    "addable": true, 
    "title": "Image"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Link", 
    "addable": true, 
    "title": "Link"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/News Item", 
    "addable": true, 
    "title": "News Item"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Document", 
    "addable": true, 
    "title": "Page"
  }
]

To get the schema of a content type, access the /@types endpoint with the name of the content type, e.g. ‘/plone/@types/Document’:

http

GET /plone/@types/Document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@types/Document -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@types/Document Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@types/Document', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json+schema

{
  "fieldsets": [
    {
      "fields": [
        "title", 
        "description", 
        "text", 
        "changeNote"
      ], 
      "id": "default", 
      "title": "Default"
    }, 
    {
      "fields": [
        "allow_discussion", 
        "exclude_from_nav", 
        "id", 
        "versioning_enabled", 
        "table_of_contents"
      ], 
      "id": "settings", 
      "title": "Settings"
    }, 
    {
      "fields": [
        "subjects", 
        "language", 
        "relatedItems"
      ], 
      "id": "categorization", 
      "title": "Categorization"
    }, 
    {
      "fields": [
        "effective", 
        "expires"
      ], 
      "id": "dates", 
      "title": "Dates"
    }, 
    {
      "fields": [
        "creators", 
        "contributors", 
        "rights"
      ], 
      "id": "ownership", 
      "title": "Ownership"
    }
  ], 
  "layouts": [
    "document_view"
  ], 
  "properties": {
    "allow_discussion": {
      "choices": [
        [
          "True", 
          "Yes"
        ], 
        [
          "False", 
          "No"
        ]
      ], 
      "description": "Allow discussion for this content object.", 
      "enum": [
        "True", 
        "False"
      ], 
      "enumNames": [
        "Yes", 
        "No"
      ], 
      "title": "Allow discussion", 
      "type": "string", 
      "vocabulary": {
        "@id": "http://localhost:55001/plone/@sources/allow_discussion"
      }
    }, 
    "changeNote": {
      "description": "Enter a comment that describes the changes you made.", 
      "title": "Change Note", 
      "type": "string"
    }, 
    "contributors": {
      "additionalItems": true, 
      "description": "The names of people that have contributed to this item. Each contributor should be on a separate line.", 
      "items": {
        "description": "", 
        "title": "", 
        "type": "string"
      }, 
      "title": "Contributors", 
      "type": "array", 
      "uniqueItems": true, 
      "widgetOptions": {
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Users"
        }
      }
    }, 
    "creators": {
      "additionalItems": true, 
      "description": "Persons responsible for creating the content of this item. Please enter a list of user names, one per line. The principal creator should come first.", 
      "items": {
        "description": "", 
        "title": "", 
        "type": "string"
      }, 
      "title": "Creators", 
      "type": "array", 
      "uniqueItems": true, 
      "widgetOptions": {
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Users"
        }
      }
    }, 
    "description": {
      "description": "Used in item listings and search results.", 
      "minLength": 0, 
      "title": "Summary", 
      "type": "string", 
      "widget": "textarea"
    }, 
    "effective": {
      "description": "If this date is in the future, the content will not show up in listings and searches until this date.", 
      "title": "Publishing Date", 
      "type": "string", 
      "widget": "datetime"
    }, 
    "exclude_from_nav": {
      "default": false, 
      "description": "If selected, this item will not appear in the navigation tree", 
      "title": "Exclude from navigation", 
      "type": "boolean"
    }, 
    "expires": {
      "description": "When this date is reached, the content will no longer be visible in listings and searches.", 
      "title": "Expiration Date", 
      "type": "string", 
      "widget": "datetime"
    }, 
    "id": {
      "description": "This name will be displayed in the URL.", 
      "title": "Short name", 
      "type": "string"
    }, 
    "language": {
      "default": "en", 
      "description": "", 
      "title": "Language", 
      "type": "string", 
      "vocabulary": {
        "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.SupportedContentLanguages"
      }
    }, 
    "relatedItems": {
      "additionalItems": true, 
      "default": [], 
      "description": "", 
      "items": {
        "description": "", 
        "title": "Related", 
        "type": "string", 
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Catalog"
        }
      }, 
      "title": "Related Items", 
      "type": "array", 
      "uniqueItems": true, 
      "widgetOptions": {
        "pattern_options": {
          "recentlyUsed": true
        }, 
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Catalog"
        }
      }
    }, 
    "rights": {
      "description": "Copyright statement or other rights information on this item.", 
      "minLength": 0, 
      "title": "Rights", 
      "type": "string", 
      "widget": "textarea"
    }, 
    "subjects": {
      "additionalItems": true, 
      "description": "Tags are commonly used for ad-hoc organization of content.", 
      "items": {
        "description": "", 
        "title": "", 
        "type": "string"
      }, 
      "title": "Tags", 
      "type": "array", 
      "uniqueItems": true, 
      "widgetOptions": {
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Keywords"
        }
      }
    }, 
    "table_of_contents": {
      "description": "If selected, this will show a table of contents at the top of the page.", 
      "title": "Table of contents", 
      "type": "boolean"
    }, 
    "text": {
      "description": "", 
      "title": "Text", 
      "type": "string", 
      "widget": "richtext"
    }, 
    "title": {
      "description": "", 
      "title": "Title", 
      "type": "string"
    }, 
    "versioning_enabled": {
      "default": true, 
      "description": "Enable/disable versioning for this document.", 
      "title": "Versioning enabled", 
      "type": "boolean"
    }
  }, 
  "required": [
    "title"
  ], 
  "title": "Page", 
  "type": "object"
}

The content type schema uses the JSON Schema format. The tagged values for the widgets are also exposed in the the “properties” attribute of the schema.

For Choice fields, their vocabulary or source will be linked to in a vocabulary or querysource property (one or the other, never both):

If a querysource property is included, that field is backed by an IQuerysource. In that case, the source’s terms can’t be enumerated, and the terms need to be queried by issuing a request to the linked endpoint and including the user’s search terms in the ?query= parameter.
If a vocabulary property is included, the field is backed by a vocabulary or another kind of iterable source. The terms can then be enumerated by issuing a request to the linked endpoint.

See Vocabularies and Sources for details on these endpoints.

See Types Schema for a detailed documentation about the available field types.

Types Schema¶

A detailed list of all available Zope Schema field types and their corresponding representation as JSON Schema .

TextLine¶

Zope Schema:

zope.schema.TextLine(
    title=u'My field',
    description=u'My great field',
    default=u'foobar'
)

JSON Schema:

{
    'type': 'string',
    'title': u'My field',
    'description': u'My great field',
    'default': u'foobar',
}

Text¶

Zope Schema:

zope.schema.Text(
    title=u'My field',
    description=u'My great field',
    default=u'Lorem ipsum dolor sit amet',
    min_length=10,
)

JSON Schema:

{
    'type': 'string',
    'title': u'My field',
    'description': u'My great field',
    'widget': 'textarea',
    'default': u'Lorem ipsum dolor sit amet',
    'minLength': 10,
}

Bool¶

Zope Schema:

zope.schema.Bool(
    title=u'My field',
    description=u'My great field',
    default=False,
)

JSON Schema:

{
    'type': 'boolean',
    'title': u'My field',
    'description': u'My great field',
    'default': False,
}

Float¶

Zope Schema:

zope.schema.Float(
    title=u'My field',
    description=u'My great field',
    min=0.0,
    max=1.0,
    default=0.5,
)

JSON Schema:

{
    'minimum': 0.0,
    'maximum': 1.0,
    'type': 'number',
    'title': u'My field',
    'description': u'My great field',
    'default': 0.5,
}

Decimal¶

Zope Schema:

zope.schema.Decimal(
    title=u'My field',
    description=u'My great field',
    min=Decimal(0),
    max=Decimal(1),
    default=Decimal(0.5),
)

JSON Schema:

{
    'minimum': 0.0,
    'maximum': 1.0,
    'type': 'number',
    'title': u'My field',
    'description': u'My great field',
    'default': 0.5,
},

Int¶

Zope Schema:

zope.schema.Int(
    title=u'My field',
    description=u'My great field',
    min=0,
    max=100,
    default=50,
)

JSON Schema:

{
    'minimum': 0,
    'maximum': 100,
    'type': 'integer',
    'title': u'My field',
    'description': u'My great field',
    'default': 50,
}

Choice¶

Zope Schema:

zope.schema.Choice(
    title=u'My field',
    description=u'My great field',
    vocabulary=self.dummy_vocabulary,
)

JSON Schema:

{
    'type': 'string',
    'title': u'My field',
    'description': u'My great field',
    'enum': ['foo', 'bar'],
    'enumNames': ['Foo', 'Bar'],
    'choices': [('foo', 'Foo'), ('bar', 'Bar')],
}

List¶

Zope Schema:

zope.schema.List(
    title=u'My field',
    description=u'My great field',
    min_length=1,
    value_type=schema.TextLine(
        title=u'Text',
        description=u'Text field',
        default=u'Default text'
    ),
    default=['foobar'],
)

JSON Schema:

{
    'type': 'array',
    'title': u'My field',
    'description': u'My great field',
    'default': ['foobar'],
    'minItems': 1,
    'uniqueItems': False,
    'additionalItems': True,
    'items': {
        'type': 'string',
        'title': u'Text',
        'description': u'Text field',
        'default': u'Default text',
    }
},

Tuple¶

Zope Schema:

field = zope.schema.Tuple(
    title=u'My field',
    value_type=schema.Int(),
    default=(1, 2),
)

JSON Schema:

{
    'type': 'array',
    'title': u'My field',
    'description': u'',
    'uniqueItems': True,
    'additionalItems': True,
    'items': {
        'title': u'',
        'description': u'',
        'type': 'integer',
    },
    'default': (1, 2),
}

Set¶

Zope Schema:

field = zope.schema.Set(
    title=u'My field',
    value_type=schema.TextLine(),
)

JSON Schema:

{
    'type': 'array',
    'title': u'My field',
    'description': u'',
    'uniqueItems': True,
    'additionalItems': True,
    'items': {
        'title': u'',
        'description': u'',
        'type': 'string',
    }
}

List of Choices¶

Zope Schema:

field = zope.schema.List(
    title=u'My field',
    value_type=schema.Choice(
        vocabulary=self.dummy_vocabulary,
    ),
)

JSON Schema:

{
    'type': 'array',
    'title': u'My field',
    'description': u'',
    'uniqueItems': True,
    'additionalItems': True,
    'items': {
        'title': u'',
        'description': u'',
        'type': 'string',
        'enum': ['foo', 'bar'],
        'enumNames': ['Foo', 'Bar'],
        'choices': [('foo', 'Foo'), ('bar', 'Bar')],
    }
}

Object¶

Zope Schema:

zope.schema.Object(
    title=u'My field',
    description=u'My great field',
    schema=IDummySchema,
)

JSON Schema:

{
    'type': 'object',
    'title': u'My field',
    'description': u'My great field',
    'properties': {
        'field1': {
            'title': u'Foo',
            'description': u'',
            'type': 'boolean'
        },
        'field2': {
            'title': u'Bar',
            'description': u'',
            'type': 'string'
        },
    }
},

RichText (plone.app.textfield)¶

Zope Schema:

from plone.app.textfield import RichText
field = RichText(
    title=u'My field',
    description=u'My great field',
)

JSON Schema:

{
    'type': 'string',
    'title': u'My field',
    'description': u'My great field',
    'widget': 'richtext',
}

Date¶

Zope Schema:

zope.schema.Date(
    title=u'My field',
    description=u'My great field',
    default=date(2016, 1, 1),
)

JSON Schema:

{
    'type': 'string',
    'title': u'My field',
    'description': u'My great field',
    'default': date(2016, 1, 1),
    'widget': u'date',
}

DateTime¶

Zope Schema:

zope.schema.Datetime(
    title=u'My field',
    description=u'My great field',
)

JSON Schema:

{
    'type': 'string',
    'title': u'My field',
    'description': u'My great field',
    'widget': u'datetime',
}

Users¶

Available users in a Plone site can be created, queried, updated and deleted by interacting with the /@users endpoint on portal root (requires an authenticated user):

List Users¶

To retrieve a list of all current users in the portal, call the /@users endpoint with a GET request:

http

GET /plone/@users HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@users -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@users Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@users', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a list of all users in the portal:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@users/admin", 
    "description": "This is an admin user", 
    "email": "admin@example.com", 
    "fullname": "Administrator", 
    "home_page": "http://www.example.com", 
    "id": "admin", 
    "location": "Berlin", 
    "portrait": null, 
    "roles": [
      "Manager"
    ], 
    "username": "admin"
  }, 
  {
    "@id": "http://localhost:55001/plone/@users/test_user_1_", 
    "description": "This is a test user", 
    "email": "test@example.com", 
    "fullname": "Test User", 
    "home_page": "http://www.example.com", 
    "id": "test_user_1_", 
    "location": "Bonn", 
    "portrait": null, 
    "roles": [
      "Manager"
    ], 
    "username": "test-user"
  }
]

This only works for Manager users, anonymous users or logged-in users without Manager rights are now allowed to list users. This is the example as an anonymous user:

http

GET /plone/@users HTTP/1.1
Accept: application/json

curl

curl -i http://nohost/plone/@users -H 'Accept: application/json'

httpie

http http://nohost/plone/@users Accept:application/json

python-requests

requests.get('http://nohost/plone/@users', headers={
    'Accept': 'application/json',
})

The server will return a 401 Unauthorized status code

HTTP/1.1 401 Unauthorized
Content-Type: application/json

null

And this one as an user without the proper rights:

http

GET /plone/@users HTTP/1.1
Accept: application/json
Authorization: Basic bm9hbTpwYXNzd29yZA==

curl

curl -i http://nohost/plone/@users -H 'Accept: application/json' --user noam:password

httpie

http http://nohost/plone/@users Accept:application/json -a noam:password

python-requests

requests.get('http://nohost/plone/@users', headers={
    'Accept': 'application/json',
}, auth=('noam', 'password'))

The server will return a 401 Unauthorized status code

HTTP/1.1 401 Unauthorized
Content-Type: application/json

null

The endpoint supports some basic filtering:

http

GET /plone/@users?query=noa HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@users?query=noa' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@users?query=noa' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@users?query=noa', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a list the filtered users in the portal with username starts with the query.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@users/noam", 
    "description": "Professor of Linguistics", 
    "email": "noam.chomsky@example.com", 
    "fullname": "Noam Avram Chomsky", 
    "home_page": "web.mit.edu/chomsky", 
    "id": "noam", 
    "location": "Cambridge, MA", 
    "portrait": null, 
    "roles": [
      "Member"
    ], 
    "username": "noam"
  }
]

The endpoint also takes a limit parameter that defaults to a maximum of 25 users at a time for performance reasons.

Create User¶

To create a new user, send a POST request to the global /@users endpoint with a JSON representation of the user you want to create in the body:

http

POST /plone/@users HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "description": "Professor of Linguistics",
    "email": "noam.chomsky@example.com",
    "fullname": "Noam Avram Chomsky",
    "home_page": "web.mit.edu/chomsky",
    "location": "Cambridge, MA",
    "password": "colorlessgreenideas",
    "roles": [
        "Contributor"
    ],
    "username": "noamchomsky"
}

curl

curl -i -X POST http://nohost/plone/@users -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"description": "Professor of Linguistics", "email": "noam.chomsky@example.com", "fullname": "Noam Avram Chomsky", "home_page": "web.mit.edu/chomsky", "location": "Cambridge, MA", "password": "colorlessgreenideas", "roles": ["Contributor"], "username": "noamchomsky"}' --user admin:secret

httpie

echo '{
  "description": "Professor of Linguistics",
  "email": "noam.chomsky@example.com",
  "fullname": "Noam Avram Chomsky",
  "home_page": "web.mit.edu/chomsky",
  "location": "Cambridge, MA",
  "password": "colorlessgreenideas",
  "roles": [
    "Contributor"
  ],
  "username": "noamchomsky"
}' | http POST http://nohost/plone/@users Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@users', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'description': 'Professor of Linguistics',
    'email': 'noam.chomsky@example.com',
    'fullname': 'Noam Avram Chomsky',
    'home_page': 'web.mit.edu/chomsky',
    'location': 'Cambridge, MA',
    'password': 'colorlessgreenideas',
    'roles': ['Contributor'],
    'username': 'noamchomsky',
}, auth=('admin', 'secret'))

Note

By default, “username”, and “password” are required fields. If email login is enabled, “email” and “password” are required fields. All other fields in the example are optional.

The field “username” is not allowed when email login is enabled.

If the user has been created successfully, the server will respond with a status 201 (Created). The Location header contains the URL of the newly created user and the resource representation in the payload:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://localhost:55001/plone/@users/noamchomsky

{
  "@id": "http://localhost:55001/plone/@users/noamchomsky", 
  "description": "Professor of Linguistics", 
  "email": "noam.chomsky@example.com", 
  "fullname": "Noam Avram Chomsky", 
  "home_page": "web.mit.edu/chomsky", 
  "id": "noamchomsky", 
  "location": "Cambridge, MA", 
  "portrait": null, 
  "roles": [
    "Contributor"
  ], 
  "username": "noamchomsky"
}

If no roles has been specified, then a default Member role is added as a sensible default.

Read User¶

To retrieve all details for a particular user, send a GET request to the /@users endpoint and append the user id to the URL:

http

GET /plone/@users/noam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@users/noam -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@users/noam Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@users/noam', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a 200 OK status code and the JSON representation of the user in the body:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@users/noam", 
  "description": "Professor of Linguistics", 
  "email": "noam.chomsky@example.com", 
  "fullname": "Noam Avram Chomsky", 
  "home_page": "web.mit.edu/chomsky", 
  "id": "noam", 
  "location": "Cambridge, MA", 
  "portrait": null, 
  "roles": [
    "Member"
  ], 
  "username": "noam"
}

The key ‘roles’ lists the globally defined roles for the user.

Only users with Manager rights are allowed to get other users’ information:

http

GET /plone/@users/noam HTTP/1.1
Accept: application/json
Authorization: Basic bm9hbS1mYWtlOnNlY3JldA==

curl

curl -i http://nohost/plone/@users/noam -H 'Accept: application/json' --user noam-fake:secret

httpie

http http://nohost/plone/@users/noam Accept:application/json -a noam-fake:secret

python-requests

requests.get('http://nohost/plone/@users/noam', headers={
    'Accept': 'application/json',
}, auth=('noam-fake', 'secret'))

If the user lacks this rights, the server will respond with a 401 Unauthorized status code:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

null

Also anonymous users are not allowed to get users’ information:

http

GET /plone/@users/noam HTTP/1.1
Accept: application/json

curl

curl -i http://nohost/plone/@users/noam -H 'Accept: application/json'

httpie

http http://nohost/plone/@users/noam Accept:application/json

python-requests

requests.get('http://nohost/plone/@users/noam', headers={
    'Accept': 'application/json',
})

If the user is an anonymous one, the server will respond with a 401 Unauthorized status code:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

null

But each user is allowed to get its own information.

http

GET /plone/@users/noam HTTP/1.1
Accept: application/json
Authorization: Basic bm9hbTpzZWNyZXQ=

curl

curl -i http://nohost/plone/@users/noam -H 'Accept: application/json' --user noam:secret

httpie

http http://nohost/plone/@users/noam Accept:application/json -a noam:secret

python-requests

requests.get('http://nohost/plone/@users/noam', headers={
    'Accept': 'application/json',
}, auth=('noam', 'secret'))

In this case, the server will respond with a 200 OK status code and the JSON respresentation of the user in the body:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@users/noam", 
  "description": "Professor of Linguistics", 
  "email": "noam.chomsky@example.com", 
  "fullname": "Noam Avram Chomsky", 
  "home_page": "web.mit.edu/chomsky", 
  "id": "noam", 
  "location": "Cambridge, MA", 
  "portrait": null, 
  "roles": [
    "Member"
  ], 
  "username": "noam"
}

Update User¶

To update the settings of a user, send a PATCH request with the user details you want to amend to the URL of that particular user, e.g. if you want to update the email address of the admin user to:

http

PATCH /plone/@users/noam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "email": "avram.chomsky@example.com",
    "roles": {
        "Contributor": false
    }
}

curl

curl -i -X PATCH http://nohost/plone/@users/noam -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"email": "avram.chomsky@example.com", "roles": {"Contributor": false}}' --user admin:secret

httpie

echo '{
  "email": "avram.chomsky@example.com",
  "roles": {
    "Contributor": false
  }
}' | http PATCH http://nohost/plone/@users/noam Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/@users/noam', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'email': 'avram.chomsky@example.com',
    'roles': {
        'Contributor': False,
    },
}, auth=('admin', 'secret'))

A successful response to a PATCH request will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content

Note

The ‘roles’ object is a mapping of a role and a boolean indicating adding or removing.

Any user is able to update their own properties and password (if allowed) by using the same request.

The user portrait/avatar can also be updated using the same serialization as the file one:

http

PATCH /plone/@users/noam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "portrait": {
        "content-type": "image/png",
        "data": "R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=",
        "encoding": "base64",
        "filename": "image.png"
    }
}

curl

curl -i -X PATCH http://nohost/plone/@users/noam -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"portrait": {"content-type": "image/png", "data": "R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=", "encoding": "base64", "filename": "image.png"}}' --user admin:secret

httpie

echo '{
  "portrait": {
    "content-type": "image/png",
    "data": "R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=",
    "encoding": "base64",
    "filename": "image.png"
  }
}' | http PATCH http://nohost/plone/@users/noam Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/@users/noam', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'portrait': {
        'content-type': 'image/png',
        'data': 'R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=',
        'encoding': 'base64',
        'filename': 'image.png',
    },
}, auth=('admin', 'secret'))

A successful response to a PATCH request will be indicated by a 204 No Content response. Then asking for the user the portrait URL should be on the response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@users/noam", 
  "description": null, 
  "email": "noam.chomsky@example.com", 
  "fullname": null, 
  "home_page": null, 
  "id": "noam", 
  "location": null, 
  "portrait": "http://localhost:55001/plone/portal_memberdata/portraits/noam", 
  "roles": [
    "Member"
  ], 
  "username": "noam"
}

Adding the portrait via the @user endpoint does not scale it since it’s assumed that the frontend will take care of it (resizing/cropping). If you still want that Plone to take care of the scaling using the default Plone behavior for portraits, you have to add the scale attribute to the request:

http

PATCH /plone/@users/noam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "portrait": {
        "content-type": "image/png",
        "data": "R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=",
        "encoding": "base64",
        "filename": "image.png",
        "scale": true
    }
}

curl

curl -i -X PATCH http://nohost/plone/@users/noam -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"portrait": {"content-type": "image/png", "data": "R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=", "encoding": "base64", "filename": "image.png", "scale": true}}' --user admin:secret

httpie

echo '{
  "portrait": {
    "content-type": "image/png",
    "data": "R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=",
    "encoding": "base64",
    "filename": "image.png",
    "scale": true
  }
}' | http PATCH http://nohost/plone/@users/noam Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/@users/noam', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'portrait': {
        'content-type': 'image/png',
        'data': 'R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=',
        'encoding': 'base64',
        'filename': 'image.png',
        'scale': True,
    },
}, auth=('admin', 'secret'))

Delete User¶

To delete a user send a DELETE request to the /@users endpoint and append the user id of the user you want to delete, e.g. to delete the user with the id johndoe:

http

DELETE /plone/@users/noam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X DELETE http://nohost/plone/@users/noam -H 'Accept: application/json' --user admin:secret

httpie

http DELETE http://nohost/plone/@users/noam Accept:application/json -a admin:secret

python-requests

requests.delete('http://nohost/plone/@users/noam', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

A successful response will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content

User registration¶

Plone allows you to enable the auto registration of users. If it is enabled, then an anonymous user can register a new user using the user creation endpoint. This new user will have the role Member by default as the Plone registration process also does.

To create a new user send a POST request to the ‘@users’ endpoint:

http

POST /plone/@users HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "description": "Professor of Linguistics",
    "email": "noam.chomsky@example.com",
    "fullname": "Noam Avram Chomsky",
    "home_page": "web.mit.edu/chomsky",
    "location": "Cambridge, MA",
    "sendPasswordReset": true,
    "username": "noamchomsky"
}

curl

curl -i -X POST http://nohost/plone/@users -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"description": "Professor of Linguistics", "email": "noam.chomsky@example.com", "fullname": "Noam Avram Chomsky", "home_page": "web.mit.edu/chomsky", "location": "Cambridge, MA", "sendPasswordReset": true, "username": "noamchomsky"}' --user admin:secret

httpie

echo '{
  "description": "Professor of Linguistics",
  "email": "noam.chomsky@example.com",
  "fullname": "Noam Avram Chomsky",
  "home_page": "web.mit.edu/chomsky",
  "location": "Cambridge, MA",
  "sendPasswordReset": true,
  "username": "noamchomsky"
}' | http POST http://nohost/plone/@users Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@users', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'description': 'Professor of Linguistics',
    'email': 'noam.chomsky@example.com',
    'fullname': 'Noam Avram Chomsky',
    'home_page': 'web.mit.edu/chomsky',
    'location': 'Cambridge, MA',
    'sendPasswordReset': True,
    'username': 'noamchomsky',
}, auth=('admin', 'secret'))

If the user should receive an email to set her password, you should pass ‘sendPasswordReset”: true’ in the JSON body of the request. Keep in mind that Plone will send a URL that points to the URL of the Plone site, which might just be your API endpoint.

If the user has been created, the server will respond with a 201 Created response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://localhost:55001/plone/@users/noamchomsky

{
  "@id": "http://localhost:55001/plone/@users/noamchomsky", 
  "description": "Professor of Linguistics", 
  "email": "noam.chomsky@example.com", 
  "fullname": "Noam Avram Chomsky", 
  "home_page": "web.mit.edu/chomsky", 
  "id": "noamchomsky", 
  "location": "Cambridge, MA", 
  "portrait": null, 
  "roles": [
    "Member"
  ], 
  "username": "noamchomsky"
}

Reset User Password¶

Plone allows to reset a password for a user by sending a POST request to the user resource and appending /reset-password to the URL:

POST /plone/@users/noam/reset-password HTTP/1.1
Host: localhost:8080
Accept: application/json

The server will respond with a 200 OK response and send an email to the user to reset her password.

The token that is part of the reset url in the email can be used to authorize setting a new password:

http

POST /plone/@users/noam/rest-password HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{"reset_token": "ef3d2aabacdc2345df63d6acf2edbef4", "new_password": "verysecret"}

curl

curl -i -X POST http://nohost/plone/@users/noam/rest-password -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"new_password": "verysecret", "reset_token": "ef3d2aabacdc2345df63d6acf2edbef4"}' --user admin:secret

httpie

echo '{
  "new_password": "verysecret",
  "reset_token": "ef3d2aabacdc2345df63d6acf2edbef4"
}' | http POST http://nohost/plone/@users/noam/rest-password Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@users/noam/rest-password', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'new_password': 'verysecret',
    'reset_token': 'ef3d2aabacdc2345df63d6acf2edbef4',
}, auth=('admin', 'secret'))

Reset Own Password¶

Plone also allows a user to reset her own password directly without sending an email. The endpoint and the request is the same as above, but now the user can send the old password and the new password as payload:

POST /plone/@users/noam/reset-password HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json

{
  'old_password': 'secret',
  'new_password': 'verysecret',
}

The server will respond with a 200 OK response without sending an email.

To set the password with the old password you need either the Set own password or the plone.app.controlpanel.UsersAndGroups permission.

If an API consumer tries to send a password in the payload that is not the same as the currently logged in user, the server will respond with a 400 Bad Request response.

Return Values¶

200 OK
400 Bad Request
403 (Unknown Token)
403 (Expired Token)
403 (Wrong user)
403 (Not allowed)
403 (Wrong password)
500 Internal Server Error (server fault, can not recover internally)

Groups¶

Available groups in a Plone site can be created, queried, updated and deleted by interacting with the /@groups endpoint on portal root (requires an authenticated user):

List Groups¶

To retrieve a list of all current groups in the portal, call the /@groups endpoint with a GET request:

http

GET /plone/@groups HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@groups -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@groups Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@groups', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a list of all groups in the portal:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@groups/Administrators", 
    "description": "", 
    "email": "", 
    "groupname": "Administrators", 
    "id": "Administrators", 
    "roles": [
      "Manager", 
      "Authenticated"
    ], 
    "title": "Administrators"
  }, 
  {
    "@id": "http://localhost:55001/plone/@groups/Reviewers", 
    "description": "", 
    "email": "", 
    "groupname": "Reviewers", 
    "id": "Reviewers", 
    "roles": [
      "Reviewer", 
      "Authenticated"
    ], 
    "title": "Reviewers"
  }, 
  {
    "@id": "http://localhost:55001/plone/@groups/Site Administrators", 
    "description": "", 
    "email": "", 
    "groupname": "Site Administrators", 
    "id": "Site Administrators", 
    "roles": [
      "Site Administrator", 
      "Authenticated"
    ], 
    "title": "Site Administrators"
  }, 
  {
    "@id": "http://localhost:55001/plone/@groups/ploneteam", 
    "description": "We are Plone", 
    "email": "ploneteam@plone.org", 
    "groupname": "ploneteam", 
    "id": "ploneteam", 
    "roles": [
      "Authenticated"
    ], 
    "title": "Plone Team"
  }, 
  {
    "@id": "http://localhost:55001/plone/@groups/AuthenticatedUsers", 
    "description": "Automatic Group Provider", 
    "email": "", 
    "groupname": "AuthenticatedUsers", 
    "id": "AuthenticatedUsers", 
    "roles": [], 
    "title": "Authenticated Users (Virtual Group)"
  }
]

The endpoint supports some basic filtering:

http

GET /plone/@groups?query=plo HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@groups?query=plo' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@groups?query=plo' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@groups?query=plo', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a list the filtered groups in the portal with groupname starts with the query.

The endpoint also takes a limit parameter that defaults to a maximum of 25 groups at a time for performance reasons.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@groups/ploneteam", 
    "description": "We are Plone", 
    "email": "ploneteam@plone.org", 
    "groupname": "ploneteam", 
    "id": "ploneteam", 
    "roles": [
      "Authenticated"
    ], 
    "title": "Plone Team"
  }
]

Create Group¶

To create a new group, send a POST request to the global /@groups endpoint with a JSON representation of the group you want to create in the body:

http

POST /plone/@groups HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "description": "The Plone Framework Team",
    "email": "fwt@plone.org",
    "groupname": "fwt",
    "groups": [
        "Administrators"
    ],
    "roles": [
        "Manager"
    ],
    "title": "Framework Team",
    "users": [
        "admin",
        "test_user_1_"
    ]
}

curl

curl -i -X POST http://nohost/plone/@groups -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"description": "The Plone Framework Team", "email": "fwt@plone.org", "groupname": "fwt", "groups": ["Administrators"], "roles": ["Manager"], "title": "Framework Team", "users": ["admin", "test_user_1_"]}' --user admin:secret

httpie

echo '{
  "description": "The Plone Framework Team",
  "email": "fwt@plone.org",
  "groupname": "fwt",
  "groups": [
    "Administrators"
  ],
  "roles": [
    "Manager"
  ],
  "title": "Framework Team",
  "users": [
    "admin",
    "test_user_1_"
  ]
}' | http POST http://nohost/plone/@groups Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@groups', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'description': 'The Plone Framework Team',
    'email': 'fwt@plone.org',
    'groupname': 'fwt',
    'groups': ['Administrators'],
    'roles': ['Manager'],
    'title': 'Framework Team',
    'users': ['admin', 'test_user_1_'],
}, auth=('admin', 'secret'))

Note

By default, “groupname” is a required field.

If the group has been created successfully, the server will respond with a status 201 (Created). The Location header contains the URL of the newly created group and the resource representation in the payload:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://localhost:55001/plone/@groups/fwt

{
  "@id": "http://localhost:55001/plone/@groups/fwt", 
  "description": "The Plone Framework Team", 
  "email": "fwt@plone.org", 
  "groupname": "fwt", 
  "id": "fwt", 
  "roles": [
    "Manager", 
    "Authenticated"
  ], 
  "title": "Framework Team", 
  "users": {
    "@id": "http://localhost:55001/plone/@groups", 
    "items": [
      "Administrators", 
      "admin", 
      "test_user_1_"
    ], 
    "items_total": 3
  }
}

Read Group¶

To retrieve all details for a particular group, send a GET request to the /@groups endpoint and append the group id to the URL:

http

GET /plone/@groups/ploneteam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@groups/ploneteam -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@groups/ploneteam Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@groups/ploneteam', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a 200 OK status code and the JSON representation of the group in the body:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@groups/ploneteam", 
  "description": "We are Plone", 
  "email": "ploneteam@plone.org", 
  "groupname": "ploneteam", 
  "id": "ploneteam", 
  "roles": [
    "Authenticated"
  ], 
  "title": "Plone Team", 
  "users": {
    "@id": "http://localhost:55001/plone/@groups/ploneteam", 
    "items": [], 
    "items_total": 0
  }
}

Batching is supported for the ‘users’ object.

Update Group¶

To update the settings of a group, send a PATCH request with the group details you want to amend to the URL of that particular group:

http

PATCH /plone/@groups/ploneteam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "email": "ploneteam2@plone.org",
    "users": {
        "test_user_1_": false
    }
}

curl

curl -i -X PATCH http://nohost/plone/@groups/ploneteam -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"email": "ploneteam2@plone.org", "users": {"test_user_1_": false}}' --user admin:secret

httpie

echo '{
  "email": "ploneteam2@plone.org",
  "users": {
    "test_user_1_": false
  }
}' | http PATCH http://nohost/plone/@groups/ploneteam Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/@groups/ploneteam', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'email': 'ploneteam2@plone.org',
    'users': {
        'test_user_1_': False,
    },
}, auth=('admin', 'secret'))

Note

The ‘users’ object is a mapping of a user_id and a boolean indicating adding or removing from the group.

A successful response to a PATCH request will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content

Delete Group¶

To delete a group send a DELETE request to the /@groups endpoint and append the group id of the group you want to delete:

http

DELETE /plone/@groups/ploneteam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X DELETE http://nohost/plone/@groups/ploneteam -H 'Accept: application/json' --user admin:secret

httpie

http DELETE http://nohost/plone/@groups/ploneteam Accept:application/json -a admin:secret

python-requests

requests.delete('http://nohost/plone/@groups/ploneteam', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

A successful response will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content

Principals¶

This endpoint will search for all the available principals in the local PAS plugins given a query string. We call a principal to any user or group in the system (requires an authenticated user):

Search Principals¶

To retrieve a list of principals given a search string, call the /@principals endpoint with a GET request and a search query parameter:

http

GET /plone/@principals?search=ploneteam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@principals?search=ploneteam' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@principals?search=ploneteam' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@principals?search=ploneteam', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a list of the users and groups in the portal that match the query string:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "groups": [
    {
      "@id": "http://localhost:55001/plone/@groups/ploneteam", 
      "description": "We are Plone", 
      "email": "ploneteam@plone.org", 
      "groupname": "ploneteam", 
      "id": "ploneteam", 
      "roles": [
        "Authenticated"
      ], 
      "title": "Plone Team"
    }
  ], 
  "users": []
}

Roles¶

Available roles in a Plone site can be queried by interacting with the /@roles endpoint on portal root (requires an authenticated user):

List Roles¶

To retrieve a list of all roles in the portal, call the /@roles endpoint with a GET request:

http

GET /plone/@roles HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@roles -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@roles Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@roles', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a list of all roles in the portal:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@roles/Contributor", 
    "@type": "role", 
    "id": "Contributor", 
    "title": "Contributor"
  }, 
  {
    "@id": "http://localhost:55001/plone/@roles/Editor", 
    "@type": "role", 
    "id": "Editor", 
    "title": "Editor"
  }, 
  {
    "@id": "http://localhost:55001/plone/@roles/Member", 
    "@type": "role", 
    "id": "Member", 
    "title": "Member"
  }, 
  {
    "@id": "http://localhost:55001/plone/@roles/Reader", 
    "@type": "role", 
    "id": "Reader", 
    "title": "Reader"
  }, 
  {
    "@id": "http://localhost:55001/plone/@roles/Reviewer", 
    "@type": "role", 
    "id": "Reviewer", 
    "title": "Reviewer"
  }, 
  {
    "@id": "http://localhost:55001/plone/@roles/Site Administrator", 
    "@type": "role", 
    "id": "Site Administrator", 
    "title": "Site Administrator"
  }, 
  {
    "@id": "http://localhost:55001/plone/@roles/Manager", 
    "@type": "role", 
    "id": "Manager", 
    "title": "Manager"
  }
]

The role title is the translated role title as displayed in Plone’s “Users and Groups” control panel.

Components¶

Warning

The @components endpoint is deprecated and has been removed in plone.restapi 1.0b1. Breadcrumbs and Navigation are now top-level endpoints.

How to get pages components (i.e. everything but the main content), like breadcrumbs, navigations, actions, etc.

Breadcrumbs¶

Getting the breadcrumbs for the current page:

http

GET /plone/front-page/@breadcrumbs HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/front-page/@breadcrumbs -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/front-page/@breadcrumbs Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@breadcrumbs', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/front-page/@breadcrumbs", 
  "items": [
    {
      "@id": "http://localhost:55001/plone/front-page", 
      "title": "Welcome to Plone"
    }
  ]
}

Navigation¶

Top-Level Navigation¶

Getting the top navigation items:

http

GET /plone/front-page/@navigation HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/front-page/@navigation -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/front-page/@navigation Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@navigation', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/front-page/@navigation", 
  "items": [
    {
      "@id": "http://localhost:55001/plone", 
      "description": "", 
      "title": "Home"
    }, 
    {
      "@id": "http://localhost:55001/plone/front-page", 
      "description": "Congratulations! You have successfully installed Plone.", 
      "title": "Welcome to Plone"
    }
  ]
}

Navigation Tree¶

Getting the navigation item tree providing a expand.navigation.depth parameter:

http

GET /plone/front-page/@navigation?expand.navigation.depth=4 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/front-page/@navigation?expand.navigation.depth=4' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/front-page/@navigation?expand.navigation.depth=4' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@navigation?expand.navigation.depth=4', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/front-page/@navigation", 
  "items": [
    {
      "@id": "http://localhost:55001/plone", 
      "description": "", 
      "items": "", 
      "title": "Home"
    }, 
    {
      "@id": "http://localhost:55001/plone/front-page", 
      "description": "Congratulations! You have successfully installed Plone.", 
      "items": [], 
      "title": "Welcome to Plone"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder", 
      "description": "", 
      "items": [
        {
          "@id": "http://localhost:55001/plone/folder/subfolder1", 
          "description": "", 
          "items": [
            {
              "@id": "http://localhost:55001/plone/folder/subfolder1/thirdlevelfolder", 
              "description": "", 
              "items": [
                {
                  "@id": "http://localhost:55001/plone/folder/subfolder1/thirdlevelfolder/fourthlevelfolder", 
                  "description": "", 
                  "title": "Fourth Level Folder"
                }
              ], 
              "title": "Third Level Folder"
            }
          ], 
          "title": "SubFolder 1"
        }, 
        {
          "@id": "http://localhost:55001/plone/folder/subfolder2", 
          "description": "", 
          "title": "SubFolder 2"
        }, 
        {
          "@id": "http://localhost:55001/plone/folder/doc1", 
          "description": "", 
          "title": "A document"
        }
      ], 
      "title": "Some Folder"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder2", 
      "description": "", 
      "items": [], 
      "title": "Some Folder 2"
    }
  ]
}

Serialization¶

Throughout the REST API, content needs to be serialized and deserialized to and from JSON representations.

In general, the format used for serializing content when reading from the API is the same as is used to submit content to the API for writing.

Basic Types¶

Basic Python data types that have a corresponding type in JSON, like integers or strings, will simply be translated between the Python type and the respective JSON type.

Dates and Times¶

Since JSON doesn’t have native support for dates/times, the Python/Zope datetime types will be serialized to an ISO 8601 datestring.

Python	JSON
`time(19, 45, 55)`	`'19:45:55'`
`date(2015, 11, 23)`	`'2015-11-23'`
`datetime(2015, 11, 23, 19, 45, 55)`	`'2015-11-23T19:45:55'`
`DateTime('2015/11/23 19:45:55')`	`'2015-11-23T19:45:55'`

RichText fields¶

RichText fields will be serialized as follows:

A RichTextValue like

RichTextValue(u'<p>Hallöchen</p>',
              mimeType='text/html',
              outputMimeType='text/html')

will be serialized to

{
  "data": "<p>Hall\u00f6chen</p>",
  "content-type": "text/html",
  "encoding": "utf-8"
}

File / Image Fields¶

Download (serialization)¶

For download, a file field will be serialized to a mapping that contains the file’s most basic metadata, and a hyperlink that the client can follow to download the file:

{
  "...": "",
  "@type": "File",
  "title": "My file",
  "file": {
    "content-type": "application/pdf",
    "download": "http://localhost:55001/plone/file/@@download/file",
    "filename": "file.pdf",
    "size": 74429
  }
}

That URL in the download property points to the regular Plone download view. The client can send a GET request to that URL with an Accept header containing the MIME type indicated in the content-type property, and will get a response containing the file.

Image fields are serialized in the same way, except that their serialization contains their width and height, and an additional property scales that contains a mapping with the available image scales. Image URLs are created using the UID-based URL that changes each time the image is modified, so these URLs can be properly cached:

{
  "icon": {
    "download": "http://localhost:55001/plone/image/@@images/8eed3f80-5e1f-4115-85b8-650a10a6ca84.png",
    "height": 32,
    "width": 24
  },
  "large": {
    "download": "http://localhost:55001/plone/image/@@images/0d1824d1-2672-4b62-9277-aeb220d3bf15.png",
    "height": 768,
    "width": 576
  },
  "..." : {}
}

Upload (deserialization)¶

For file or image fields, the client must provide the file’s data as a mapping containg the file data and some additional metadata:

data - the base64 encoded contents of the file
encoding - the encoding you used to encode the data, so usually base64
content-type - the MIME type of the file
filename - the name of the file, including extension

{
  "...": "",
  "@type": "File",
  "title": "My file",
  "file": {
      "data": "TG9yZW0gSXBzdW0uCg==",
      "encoding": "base64",
      "filename": "lorem.txt",
      "content-type": "text/plain"}
}

Relations¶

Serialization¶

A RelationValue will be serialized to a short summary representation of the referenced object:

{
  "@id": "http://nohost/plone/doc1",
  "@type": "DXTestDocument",
  "title": "Document 1",
  "description": "Description"
}

The RelationList containing that reference will be represended as a list in JSON.

Deserialization¶

In order to set a relation when creating or updating content, you can use one of several ways to specify relations:

UID
path
URL
intid

Specify relations by UID:

{
  "relatedItems": [
    "158e5361282647e39bf0698fe238814b",
    "5597250bda4b41eab6ed37cd25fb0979"
  ]
}

Specify relations by path:

{
  "relatedItems": ["/page1", "/page2"]
}

Specify relations by URL:

{
  "relatedItems": [
    "http://localhost:8080/Plone/page1",
    "http://localhost:8080/Plone/page2"
  ]
}

Specify relations by intid:

{
  "relatedItems": [347127075, 347127076]
}

Search¶

Content in a Plone site can be searched for by invoking the /@search endpoint on any context:

GET /plone/@search HTTP/1.1
Accept: application/json

A search is contextual by default, i.e. it is bound to a specific context (a collection in HTTP REST terms) and searches within that collection and any sub-collections.

Since a Plone site is also a collection, we therefore have a global search (by invoking the /@search endpoint on the site root) and contextual searches (by invoking that endpoint on any other context) all using the same pattern.

In terms of the resulting catalog query this means that, by default, a search will be constrained by the path to the context it’s invoked on, unless you explicitly supply your own path query.

Search results are represented similar to collections:

http

GET /plone/@search?sort_on=path HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@search?sort_on=path' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@search?sort_on=path' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@search?sort_on=path', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@search", 
  "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
}

The default representation for search results is a summary that contains only the most basic information. In order to return specific metadata columns, see the documentation of the metadata_fields parameter below.

Note

A search invoked on a container will by default include that container itself as part of the search results. This is the same behavior as displayed by ZCatalog, which is used internally. If you add the query string parameter depth=1 to your search, you will only get immediate children of the container, and the container itself also won’t be part of the results. See the Plone docs on searching for content within a folder. for more details.

Note

Search results 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.

Warning

The @@search view or in Plone LiveSearch widget are coded in a way that the SearchableText parameter is expanded by including a * wildcard at the end. This is done in order to match also the partial results of the beginning of a search term(s). plone.restapi @search endpoint will not do that for you. You’ll have to add it if you want to keep this feature.

Query format¶

Queries and query-wide options (like sort_on) are submitted as query string parameters to the /@search request:

GET /plone/@search?SearchableText=lorem HTTP/1.1

This is nearly identical to the way that queries are passed to the Plone @@search browser view, with only a few minor differences.

For general information on how to query the Plone catalog, please refer to the Plone Documentation on Querying.

Query options¶

In case you want to supply query options to a query against a particular index, you’ll need to flatten the corresponding query dictionary and use a dotted notation to indicate nesting.

For example, to specify the depth query option for a path query, the original query as a Python dictionary would look like this:

query = {'path': {'query': '/folder',
                  'depth': 2}}

This dictionary will need to be flattened in dotted notation in order to pass it in a query string:

http

GET /plone/@search?sort_on=path&path.query=%2Fplone%2Ffolder1&path.depth=1 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@search?sort_on=path&path.query=%2Fplone%2Ffolder1&path.depth=1' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@search?sort_on=path&path.query=%2Fplone%2Ffolder1&path.depth=1' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@search?sort_on=path&path.query=%2Fplone%2Ffolder1&path.depth=1', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@search?path.query=%2Fplone%2Ffolder1&path.depth=1", 
  "items": [
    {
      "@id": "http://localhost:55001/plone/folder1/folder2", 
      "@type": "Folder", 
      "description": "", 
      "review_state": "private", 
      "title": "Folder 2"
    }
  ], 
  "items_total": 1
}

Again, this is very similar to how Record Arguments are parsed by ZPublisher, except that you can omit the :record suffix.

Restricting search to multiple paths¶

To restrict search to multiple paths, the original query as a Python dictionary would look like this (with an optional depth and sort_on):

query = {'path': {'query': ('/folder', '/folder2'),
                  'depth': 2},
         'sort_on': 'path'}

This dictionary will need to be flattened in dotted notation in order to pass it in a query string. In order to specify multiple paths, simply repeat the query string parameter (the requests module will do this automatically for you if you pass it a list of values for a query string parameter).

http

GET /plone/@search?sort_on=path&path.query=%2Fplone%2Ffolder1&path.query=%2Fplone%2Ffolder2&path.depth=2 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@search?sort_on=path&path.query=%2Fplone%2Ffolder1&path.query=%2Fplone%2Ffolder2&path.depth=2' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@search?sort_on=path&path.query=%2Fplone%2Ffolder1&path.query=%2Fplone%2Ffolder2&path.depth=2' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@search?sort_on=path&path.query=%2Fplone%2Ffolder1&path.query=%2Fplone%2Ffolder2&path.depth=2', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@search?path.query=%2Fplone%2Ffolder1&path.query=%2Fplone%2Ffolder2&path.depth=2", 
  "items": [
    {
      "@id": "http://localhost:55001/plone/folder1", 
      "@type": "Folder", 
      "description": "", 
      "review_state": "private", 
      "title": "Folder 1"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder1/doc1", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "Lorem Ipsum"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder2", 
      "@type": "Folder", 
      "description": "", 
      "review_state": "private", 
      "title": "Folder 2"
    }, 
    {
      "@id": "http://localhost:55001/plone/folder2/doc2", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "Lorem Ipsum"
    }
  ], 
  "items_total": 4
}

Data types in queries¶

Because HTTP query strings contain no information about data types, any query string parameter value ends up as a string in the Zope’s request. This means, that for values types that aren’t string, these data types need to be reconstructed on the server side in plone.restapi.

For most index types and their query values and query options, plone.restapi can handle this for you. If you pass it path.query=foo&path.depth=1, it has the necessary knowledge about the ExtendedPathIndex’s options to turn the string 1 for the depth argument back into an integer before passing the query on to the catalog.

However, certain index types (a FieldIndex for example) may take arbitrary data types as query values. In that case, plone.restapi simply can’t know what data type to cast your query value to, and you’ll need to specify it using ZPublisher type hints:

GET /plone/@search?numeric_field=42:int HTTP/1.1
Accept: application/json

Please refer to the Documentation on Argument Conversion in ZPublisher for details.

Retrieving additional metadata¶

By default the results are represented as summaries that only contain the most basic information about the items, like their URL and title. If you need to retrieve additional metadata columns, you can do so by specifying the additional column names in the metadata_fields parameter:

http

GET /plone/@search?SearchableText=lorem&metadata_fields=modified&metadata_fields=created HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@search?SearchableText=lorem&metadata_fields=modified&metadata_fields=created' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@search?SearchableText=lorem&metadata_fields=modified&metadata_fields=created' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@search?SearchableText=lorem&metadata_fields=modified&metadata_fields=created', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@search?SearchableText=lorem&metadata_fields=modified&metadata_fields=created", 
  "items": [
    {
      "@id": "http://localhost:55001/plone/doc1", 
      "@type": "Document", 
      "created": "1995-07-31T13:45:00", 
      "description": "", 
      "modified": "1995-07-31T17:30:00", 
      "review_state": "private", 
      "title": "Lorem Ipsum"
    }
  ], 
  "items_total": 1
}

The metadata from those columns then will be included in the results. In order to specify multiple columns, simply repeat the query string parameter once for every column name (the requests module will do this automatically for you if you pass it a list of values for a query string parameter).

In order to retrieve all metadata columns that the catalog knows about, use metadata_fields=_all.

Retrieving full objects¶

If the data provided as metadata is not enough, you can retrieve search results as full serialized objects equivalent to what the resource GET request would produce.

You do so by specifying the fullobjects parameter:

http

GET /plone/@search?SearchableText=lorem&fullobjects=1 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@search?SearchableText=lorem&fullobjects=1' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@search?SearchableText=lorem&fullobjects=1' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@search?SearchableText=lorem&fullobjects=1', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@search?SearchableText=lorem&fullobjects=1", 
  "items": [
    {
      "@components": {
        "actions": {
          "@id": "http://localhost:55001/plone/doc1/@actions"
        }, 
        "breadcrumbs": {
          "@id": "http://localhost:55001/plone/doc1/@breadcrumbs"
        }, 
        "navigation": {
          "@id": "http://localhost:55001/plone/doc1/@navigation"
        }, 
        "types": {
          "@id": "http://localhost:55001/plone/doc1/@types"
        }, 
        "workflow": {
          "@id": "http://localhost:55001/plone/doc1/@workflow"
        }
      }, 
      "@id": "http://localhost:55001/plone/doc1", 
      "@type": "Document", 
      "UID": "SomeUUID000000000000000000000002", 
      "allow_discussion": false, 
      "changeNote": "", 
      "contributors": [], 
      "created": "1995-07-31T13:45:00", 
      "creators": [
        "test_user_1_"
      ], 
      "description": "", 
      "effective": null, 
      "exclude_from_nav": false, 
      "expires": null, 
      "id": "doc1", 
      "is_folderish": false, 
      "language": "", 
      "layout": "document_view", 
      "modified": "1995-07-31T17:30:00", 
      "parent": {
        "@id": "http://localhost:55001/plone", 
        "@type": "Plone Site", 
        "description": "", 
        "title": "Plone site"
      }, 
      "relatedItems": [], 
      "review_state": "private", 
      "rights": "", 
      "subjects": [], 
      "table_of_contents": null, 
      "text": null, 
      "title": "Lorem Ipsum", 
      "version": "current", 
      "versioning_enabled": true
    }
  ], 
  "items_total": 1
}

Warning

Be aware that this might induce performance issues when retrieving a lot of resources. Normally the search just serializes catalog brains, but with full objects we wake up all the returned objects.

TUS resumable upload¶

plone.restapi supports the TUS Open Protocol for resumable file uploads. There is a @tus-upload endpoint to upload a file and a @tus-replace endpoint to replace an existing file.

Creating an Upload URL¶

Note

POST requests to the @tus-upload endpoint are allowed on all IFolderish content types (e.g. Folder).

To create a new upload, send a POST request to the @tus-upload endpoint.

http

POST /plone/folder/@tus-upload HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Tus-Resumable: 1.0.0
Upload-Length: 8
Upload-Metadata: filename dGVzdC50eHQ=,content-type dGV4dC9wbGFpbg==

curl

curl -i -X POST http://nohost/plone/folder/@tus-upload -H 'Accept: application/json' -H 'Tus-Resumable: 1.0.0' -H 'Upload-Length: 8' -H 'Upload-Metadata: filename dGVzdC50eHQ=,content-type dGV4dC9wbGFpbg==' --user admin:secret

httpie

http POST http://nohost/plone/folder/@tus-upload Accept:application/json Tus-Resumable:1.0.0 Upload-Length:8 Upload-Metadata:'filename dGVzdC50eHQ=,content-type dGV4dC9wbGFpbg==' -a admin:secret

python-requests

requests.post('http://nohost/plone/folder/@tus-upload', headers={
    'Accept': 'application/json',
    'Tus-Resumable': '1.0.0',
    'Upload-Length': '8',
    'Upload-Metadata': 'filename dGVzdC50eHQ=,content-type dGV4dC9wbGFpbg==',
}, auth=('admin', 'secret'))

The server will return a temporary upload URL in the location header of the response:

HTTP/1.1 201 Created
Location: http://localhost:55001/plone/folder/@tus-upload/032803b64ad746b3ab46d9223ea3d90f
Tus-Resumable: 1.0.0

The file can then be uploaded in the next step to that temporary URL.

Uploading a File¶

Note

PATCH requests to the @tus-upload endpoint are allowed on all IContentish content types.

Once a temporary upload URL has been created, a client can send a PATCH request to upload a file. The file content should be send in the body of the request:

PATCH /plone/folder/@tus-upload/032803b64ad746b3ab46d9223ea3d90f HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Tus-Resumable: 1.0.0
Upload-Offset: 3
Content-Type: application/offset+octet-stream

defgh

When just a single file is uploaded at once, the server will respond with a 204: No Content response after a successful upload. The HTTP location header contains he URL of the newly created content object:

HTTP/1.1 204 No Content
Location: http://localhost:55001/plone/folder/document-2016-10-21
Tus-Resumable: 1.0.0
Upload-Offset: 8

Partial Upload¶

TUS allows partial upload of files. A partial file is also uploaded by sending a PATCH request to the temporary URL:

PATCH /plone/folder/@tus-upload/032803b64ad746b3ab46d9223ea3d90f HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Tus-Resumable: 1.0.0
Upload-Offset: 0
Content-Type: application/offset+octet-stream

abc

The server will also respond with a 204: No content response. Though, instead of providing the final file URL in the ‘location’ header, the server provides an updated ‘Upload-Offset’ value, to tell the client the new offset:

HTTP/1.1 204 No Content
Tus-Resumable: 1.0.0
Upload-Offset: 3

When the last partial file has been uploaded, the server will contain the final file URL in the ‘location’ header.

Replacing Existing Files¶

TUS can also be used to replace an existing file by sending a POST request to the @tus-replace endpoint instead.

POST /plone/myfile/@tus-replace HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Tus-Resumable: 1.0.0
Upload-Length: 8
Upload-Metadata: filename dGVzdC50eHQ=,content-type dGV4dC9wbGFpbg==

The server will respond with a 201: Created status and return the URL of the temprorary created upload resource in the location header of the response:

HTTP/1.1 201 Created
Location: http://localhost:55001/plone/folder/@tus-upload/032803b64ad746b3ab46d9223ea3d90f
Tus-Resumable: 1.0.0

The file can then be uploaded to that URL using the PATCH method in the same way as creating a new file:

PATCH /plone/myfile/@tus-upload/4e465958b24a46ec8657e6f3be720991 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Tus-Resumable: 1.0.0
Upload-Offset: 0
Content-Type: application/offset+octet-stream

abcdefgh

The server will respond with a 204: No Content response and the final file URL in the HTTP location header:

HTTP/1.1 204 No Content
Location: http://localhost:55001/plone/myfile
Tus-Resumable: 1.0.0
Upload-Offset: 8

Asking for the Current File Offset¶

To ask the server for the current file offset, the client can send a HEAD request to the upload URL:

http

HEAD /plone/folder/@tus-upload/032803b64ad746b3ab46d9223ea3d90f HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Tus-Resumable: 1.0.0

curl

curl -i -X HEAD http://nohost/plone/folder/@tus-upload/032803b64ad746b3ab46d9223ea3d90f -H 'Accept: application/json' -H 'Tus-Resumable: 1.0.0' --user admin:secret

httpie

http HEAD http://nohost/plone/folder/@tus-upload/032803b64ad746b3ab46d9223ea3d90f Accept:application/json Tus-Resumable:1.0.0 -a admin:secret

python-requests

requests.head('http://nohost/plone/folder/@tus-upload/032803b64ad746b3ab46d9223ea3d90f', headers={
    'Accept': 'application/json',
    'Tus-Resumable': '1.0.0',
}, auth=('admin', 'secret'))

The server will respond with a 200: Ok status and the current file offset in the ‘Upload-Offset’ header:

HTTP/1.1 200 OK
Tus-Resumable: 1.0.0
Upload-Length: 8
Upload-Offset: 3

Configuration and Options¶

The current TUS configuration and a list of supported options can be retrieved sending an OPTIONS request to the @tus-upload endpoint:

http

OPTIONS /plone/folder/@tus-upload HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X OPTIONS http://nohost/plone/folder/@tus-upload -H 'Accept: application/json' --user admin:secret

httpie

http OPTIONS http://nohost/plone/folder/@tus-upload Accept:application/json -a admin:secret

python-requests

requests.options('http://nohost/plone/folder/@tus-upload', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a 204: No content status and HTTP headers containing information about the available extentions and the TUS version:

HTTP/1.1 204 No Content
Tus-Extension: creation,expiration
Tus-Resumable: 1.0.0
Tus-Version: 1.0.0

CORS Configuration¶

If you use CORS and want to make it work with TUS, you have to make sure the TUS specific HTTP headers are allowed by your CORS policy.

<plone:CORSPolicy
  allow_origin="http://localhost"
  allow_methods="DELETE,GET,OPTIONS,PATCH,POST,PUT"
  allow_credentials="true"
  allow_headers="Accept,Authorization,Origin,X-Requested-With,Content-Type,Upload-Length,Upload-Offset,Tus-Resumable,Upload-Metadata"
  expose_headers="Upload-Offset,Location,Upload-Length,Tus-Version,Tus-Resumable,Tus-Max-Size,Tus-Extension,Upload-Metadata"
  max_age="3600"
  />

See the plone.rest documentation for more information on how to configure CORS policies.

See http://tus.io/protocols/resumable-upload.html#headers for a list and description of the individual headers.

Temporary Upload Directory¶

During upload files are stored in a temporary directory that by default is located in the CLIENT_HOME directory. If you are using a multi ZEO client setup without session stickiness you must configure this to a directory shared by all ZEO clients by setting the TUS_TMP_FILE_DIR environment variable. E.g. TUS_TMP_FILE_DIR=/tmp/tus-uploads

Vocabularies and Sources¶

Vocabularies are a set of allowed choices that back a particular field. They contain so called terms which represent those allowed choices. Sources are a similar, but are a more generic and dynamic concept.

Concepts¶

Vocabularies contain a list of terms. These terms are usually tokenized, meaning that in addition to a term’s value, it also has a token which is a machine-friendly identifier for the term (7bit ASCII).

Note

Since the underlying value of a term might not necessarily be serializable (it could be an arbitrary Python object), plone.restapi only exposes and accepts tokens, and will transparently convert between tokens and values during serialization / deseralization. For this reason, the following endpoints only support tokenized vocabularies / sources, and they do not expose the terms’ values.

Terms can also have a title, which is intended to be the user-facing label for the term. For vocabularies or sources whose terms are only tokenized, but not titled, plone.restapi will fall back to using the token as the term title.

Sources are similar to vocabularies, but they tend to be more dynamic in nature, and are often used for larger sets of terms. They are also not registered with a global name like vocabularies, but are instead addressed via the field they are assigned to.

Query Sources are sources that are capable of being queried / searched. The source will then return only the subset of terms that match the query.

The use of such a source is usually a strong indication that no attempt should be made to enumerate the full set of terms, but instead the source should only be queried, by presenting the user with an autocomplete widget for example.

Both vocabularies and sources can be context-sensitive, meaning that they take the context into account and their contents may therefore change depending on the context they’re invoked on.

This section can only provide a basic overview of vocabularies and related concepts. For a more in-depth explanation please refer to the Plone documentation.

Endpoints overview¶

In plone.restapi these three concepts are exposed through three separate endpoints (described in more detail below):

@vocabularies/(vocab_name)
@sources/(field_name)
@querysources/(field_name) ?query= (search_query)

While the @vocabularies and @sources endpoints allow to enumerate terms (and optionally have terms filtered server-side), the @querysources endpoint only allows for searching the respective source.

List all vocabularies¶

GET (context)/@vocabularies¶

To retrieve a list of all the available vocabularies, send a GET request to the @vocabularies endpoint:

http

GET /plone/@vocabularies HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@vocabularies -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@vocabularies Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@vocabularies', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The response will include a list with the URL (@id) and the names (title) of all the available vocabularies in Plone:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.content.ValidAddableTypes", 
    "title": "plone.app.content.ValidAddableTypes"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.contentrules.events", 
    "title": "plone.contentrules.events"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AvailableContentLanguages", 
    "title": "plone.app.vocabularies.AvailableContentLanguages"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.SupportedContentLanguages", 
    "title": "plone.app.vocabularies.SupportedContentLanguages"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Roles", 
    "title": "plone.app.vocabularies.Roles"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Permissions", 
    "title": "plone.app.vocabularies.Permissions"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AllowedContentTypes", 
    "title": "plone.app.vocabularies.AllowedContentTypes"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AllowableContentTypes", 
    "title": "plone.app.vocabularies.AllowableContentTypes"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.PortalTypes", 
    "title": "plone.app.vocabularies.PortalTypes"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes", 
    "title": "plone.app.vocabularies.ReallyUserFriendlyTypes"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.UserFriendlyTypes", 
    "title": "plone.app.vocabularies.UserFriendlyTypes"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Skins", 
    "title": "plone.app.vocabularies.Skins"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Workflows", 
    "title": "plone.app.vocabularies.Workflows"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.WorkflowStates", 
    "title": "plone.app.vocabularies.WorkflowStates"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.WorkflowTransitions", 
    "title": "plone.app.vocabularies.WorkflowTransitions"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AvailableEditors", 
    "title": "plone.app.vocabularies.AvailableEditors"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Keywords", 
    "title": "plone.app.vocabularies.Keywords"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.SyndicationFeedTypes", 
    "title": "plone.app.vocabularies.SyndicationFeedTypes"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.SyndicatableFeedItems", 
    "title": "plone.app.vocabularies.SyndicatableFeedItems"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Users", 
    "title": "plone.app.vocabularies.Users"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Groups", 
    "title": "plone.app.vocabularies.Groups"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Principals", 
    "title": "plone.app.vocabularies.Principals"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Catalog", 
    "title": "plone.app.vocabularies.Catalog"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Actions", 
    "title": "plone.app.vocabularies.Actions"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.PortalActionCategories", 
    "title": "plone.app.vocabularies.PortalActionCategories"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Timezones", 
    "title": "plone.app.vocabularies.Timezones"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.CommonTimezones", 
    "title": "plone.app.vocabularies.CommonTimezones"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AvailableTimezones", 
    "title": "plone.app.vocabularies.AvailableTimezones"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Weekdays", 
    "title": "plone.app.vocabularies.Weekdays"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.WeekdaysAbbr", 
    "title": "plone.app.vocabularies.WeekdaysAbbr"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.WeekdaysShort", 
    "title": "plone.app.vocabularies.WeekdaysShort"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Month", 
    "title": "plone.app.vocabularies.Month"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.MonthAbbr", 
    "title": "plone.app.vocabularies.MonthAbbr"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ImagesScales", 
    "title": "plone.app.vocabularies.ImagesScales"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/Fields", 
    "title": "Fields"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.schemaeditor.VocabulariesVocabulary", 
    "title": "plone.schemaeditor.VocabulariesVocabulary"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/Behaviors", 
    "title": "Behaviors"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.formwidget.relations.cmfcontentsearch", 
    "title": "plone.formwidget.relations.cmfcontentsearch"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.event.SynchronizationStrategies", 
    "title": "plone.app.event.SynchronizationStrategies"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.contenttypes.metadatafields", 
    "title": "plone.app.contenttypes.metadatafields"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/Interfaces", 
    "title": "Interfaces"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.discussion.vocabularies.CaptchaVocabulary", 
    "title": "plone.app.discussion.vocabularies.CaptchaVocabulary"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.discussion.vocabularies.TextTransformVocabulary", 
    "title": "plone.app.discussion.vocabularies.TextTransformVocabulary"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.users.user_registration_fields", 
    "title": "plone.app.users.user_registration_fields"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.users.group_ids", 
    "title": "plone.app.users.group_ids"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.multilingual.vocabularies.AllContentLanguageVocabulary", 
    "title": "plone.app.multilingual.vocabularies.AllContentLanguageVocabulary"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.multilingual.vocabularies.AllAvailableLanguageVocabulary", 
    "title": "plone.app.multilingual.vocabularies.AllAvailableLanguageVocabulary"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.multilingual.RootCatalog", 
    "title": "plone.app.multilingual.RootCatalog"
  }, 
  {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.restapi.testing.context_vocabulary", 
    "title": "plone.restapi.testing.context_vocabulary"
  }
]

Get a vocabulary¶

GET (context)/@vocabularies/(vocab_name)¶

To enumerate the terms of a particular vocabulary, use the @vocabularies endpoint with the name of the vocabulary, e.g. /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes. The endpoint can be used with the site root and content objects.

http

GET /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a list of terms. The title is purely for display purposes. The token is what should be sent to the server to address that term.

Note

Vocabulary terms 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.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes", 
  "items": [
    {
      "title": "Collection", 
      "token": "Collection"
    }, 
    {
      "title": "Comment", 
      "token": "Discussion Item"
    }, 
    {
      "title": "DX Test Document", 
      "token": "DXTestDocument"
    }, 
    {
      "title": "Event", 
      "token": "Event"
    }, 
    {
      "title": "File", 
      "token": "File"
    }, 
    {
      "title": "Folder", 
      "token": "Folder"
    }, 
    {
      "title": "Image", 
      "token": "Image"
    }, 
    {
      "title": "Link", 
      "token": "Link"
    }, 
    {
      "title": "News Item", 
      "token": "News Item"
    }, 
    {
      "title": "Page", 
      "token": "Document"
    }, 
    {
      "title": "Test Document", 
      "token": "ATTestDocument"
    }, 
    {
      "title": "Test Folder", 
      "token": "ATTestFolder"
    }
  ], 
  "items_total": 12
}

Filter Vocabularies¶

GET (context)/@vocabularies/(vocab_name)?title=(filter_query)¶

GET (context)/@vocabularies/(vocab_name)?token=(filter_query)¶

Vocabulary terms can be filtered using the title or token parameter.

Use the title paramenter to filter vocabulary terms by title. E.g. search for all terms that contain the string doc in the title:

http

GET /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?title=doc", 
  "items": [
    {
      "title": "DX Test Document", 
      "token": "DXTestDocument"
    }, 
    {
      "title": "Test Document", 
      "token": "ATTestDocument"
    }
  ], 
  "items_total": 2
}

Use the token paramenter to filter vocabulary terms by token. This is useful in case that you have the token and you need to retrieve the title. E.g. search the term doc in the token:

http

GET /plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes?token=Document", 
  "items": [
    {
      "title": "Page", 
      "token": "Document"
    }
  ], 
  "items_total": 1
}

Note

You must not filter by title and token at the same time. The API returns a 400 response code if you do so.

Get a source¶

GET (context)/@sources/(field_name)¶

To enumerate the terms of a field’s source, use the @sources endpoint on a specific context, and pass the field name as a path parameter, e.g. /plone/doc/@sources/some_field.

Because sources are inherently tied to a specific field, this endpoint can only be invoked on content objects, and the source is addressed via the field name its used for, instead of a global name (which sources don’t have).

Otherwise the endpoint behaves the same as the @vocabularies endpoint.

Example:

http

GET /plone/doc/@sources/test_choice_with_source HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/doc/@sources/test_choice_with_source -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/doc/@sources/test_choice_with_source Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/doc/@sources/test_choice_with_source', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a list of terms. The title is purely for display purposes. The token is what should be sent to the server to address that term.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/doc/@sources/test_choice_with_source", 
  "items": [
    {
      "title": "Title 1", 
      "token": "token1"
    }, 
    {
      "title": "Title 2", 
      "token": "token2"
    }, 
    {
      "title": "Title 3", 
      "token": "token3"
    }
  ], 
  "items_total": 3
}

Note

Technically there can be sources that are not iterable (ones that only implement ISource, but not IIterableSource). These cannot be enumerated using the @sources endpoint, and it will respond with a corresponding error.

Querying a query source¶

GET (context)/@querysources/(field_name)?query=(search_query)¶

Query sources (sources implementing IQuerySource) can be queried using this endpoint, by passing the search term in the query parameter. This search term will be passed to the query source’s search() method, and the source’s results are returned.

Example:

http

GET /plone/doc/@querysources/test_choice_with_querysource?query=2 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/doc/@querysources/test_choice_with_querysource?query=2' -H 'Accept: application/json' --user admin:secret

httpie

http 'http://nohost/plone/doc/@querysources/test_choice_with_querysource?query=2' Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/doc/@querysources/test_choice_with_querysource?query=2', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with a list of terms. The title is purely for display purposes. The token is what should be sent to the server to address that term.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/doc/@querysources/test_choice_with_querysource?query=2", 
  "items": [
    {
      "title": "Title 2", 
      "token": "token2"
    }
  ], 
  "items_total": 1
}

Note

Even though technically sources that implement IQuerySource are required to implement __iter__ as well (when strictly following the interface interitance hierarchy), they usually are used in Plone in situations where their full contents shouldn’t or can’t be enumerated (imagine a source of all users, backed by a large LDAP, for example).

For this reason, plone.restapi takes the stance that the IQuerySource interface is a strong indication that this source should only be queried, and therefore doesn’t support enumeration of terms via the @querysources endpoint.

(If the source does actually implement IIterableSource in addition to IQuerySource, it can still be enumerated via the @sources endpoint)

Control Panels¶

Control panels in Plone allow you to configure the global site setup of a Plone site. The @controlpanels endpoint in plone.restapi allows you to list all existing control panels in a Plone site and to retrieve or edit the settings of a specific control panel.

Most of the settings in the Plone control panels are based on plone.registry (since Plone 5.x). Therefore you can also use the @registry endpoint to retrieve or manipulate site settings. The @controlpanels endpoint just gives developers are more a convenience way of accessing the settings and makes it easier to render control panels on the front-end.

Note

This is currently only implemented for Plone 5.

Listing Control Panels¶

A list of all existing control panels in the portal can be retrieved by sending a GET request to the @controlpanels endpoint:

http

GET /plone/@controlpanels HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@controlpanels -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@controlpanels Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@controlpanels', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@controlpanels/date-and-time", 
    "group": "General", 
    "title": "Date and Time"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/language", 
    "group": "General", 
    "title": "Language"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/mail", 
    "group": "General", 
    "title": "Mail"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/navigation", 
    "group": "General", 
    "title": "Navigation"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/site", 
    "group": "General", 
    "title": "Site"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/search", 
    "group": "General", 
    "title": "Search"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/socialmedia", 
    "group": "General", 
    "title": "Social Media"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/editing", 
    "group": "Content", 
    "title": "Editing"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/imaging", 
    "group": "Content", 
    "title": "Image Handling"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/markup", 
    "group": "Content", 
    "title": "Markup"
  }, 
  {
    "@id": "http://localhost:55001/plone/@controlpanels/security", 
    "group": "Security", 
    "title": "Security"
  }
]

The following fields are returned:

@id: hypermedia link to the control panel
title: the title of the control panel
group: the group where the control panel should show up (e.g. General, Content, Users, Security, Advanced, Add-on Configuration)

Retrieve a single Control Panel¶

To retrieve a single control panel, send a GET request to the URL of the control panel:

http

GET /plone/@controlpanels/editing HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@controlpanels/editing -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@controlpanels/editing Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@controlpanels/editing', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@controlpanels/editing", 
  "data": {
    "available_editors": [
      "TinyMCE", 
      "None"
    ], 
    "default_editor": {
      "title": "TinyMCE", 
      "token": "TinyMCE"
    }, 
    "enable_link_integrity_checks": true, 
    "ext_editor": false, 
    "lock_on_ttw_edit": true, 
    "subjects_of_navigation_root": false
  }, 
  "group": "Content", 
  "schema": {
    "fieldsets": [
      {
        "fields": [
          "available_editors", 
          "default_editor", 
          "ext_editor", 
          "enable_link_integrity_checks", 
          "lock_on_ttw_edit", 
          "subjects_of_navigation_root"
        ], 
        "id": "default", 
        "title": "Default"
      }
    ], 
    "properties": {
      "available_editors": {
        "additionalItems": true, 
        "default": [
          "TinyMCE", 
          "None"
        ], 
        "description": "Available editors in the portal.", 
        "items": {
          "description": "", 
          "title": "", 
          "type": "string"
        }, 
        "title": "Available editors", 
        "type": "array", 
        "uniqueItems": false
      }, 
      "default_editor": {
        "default": "TinyMCE", 
        "description": "Select the default wysiwyg editor. Users will be able to choose their own or select to use the site default.", 
        "title": "Default editor", 
        "type": "string", 
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.AvailableEditors"
        }
      }, 
      "enable_link_integrity_checks": {
        "default": true, 
        "description": "Determines if the users should get warnings when they delete or move content that is linked from inside the site.", 
        "title": "Enable link integrity checks", 
        "type": "boolean"
      }, 
      "ext_editor": {
        "default": false, 
        "description": "Determines if the external editor feature is enabled. This feature requires a special client-side application installed. The users also have to enable this in their preferences.", 
        "title": "Enable External Editor feature", 
        "type": "boolean"
      }, 
      "lock_on_ttw_edit": {
        "default": true, 
        "description": "Disabling locking here will only affect users editing content through the Plone web UI.  Content edited via WebDAV clients will still be subject to locking.", 
        "title": "Enable locking for through-the-web edits", 
        "type": "boolean"
      }, 
      "subjects_of_navigation_root": {
        "default": false, 
        "description": "Limit tags aka keywords vocabulary used for Tags field and in searches to the terms used inside the subtree of the current navigation root. This can be used together with Plone's multilingual extension plone.app.multilingual to only offer keywords of the current selected language. Other addons may utilize this feature for its specific purposes.", 
        "title": "Limit tags/keywords to the current navigation root", 
        "type": "boolean"
      }
    }, 
    "required": [
      "available_editors", 
      "default_editor"
    ], 
    "type": "object"
  }, 
  "title": "Editing"
}

The following fields are returned:

@id: hypermedia link to the control panel
title: title of the control panel
group: group name of the control panel
schema: JSON Schema of the control panel
data: current values of the control panel

Updating a Control Panel with PATCH¶

To update the settings on a control panel send a PATCH request to control panel resource:

http

PATCH /plone/@controlpanels/editing HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
  "default_editor": "CKeditor",
  "ext_editor": true
}

curl

curl -i -X PATCH http://nohost/plone/@controlpanels/editing -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"default_editor": "CKeditor", "ext_editor": true}' --user admin:secret

httpie

echo '{
  "default_editor": "CKeditor",
  "ext_editor": true
}' | http PATCH http://nohost/plone/@controlpanels/editing Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.patch('http://nohost/plone/@controlpanels/editing', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'default_editor': 'CKeditor',
    'ext_editor': True,
}, auth=('admin', 'secret'))

A successful response to a PATCH request will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content

Tiles¶

Note

The tiles endpoint currently match only partially (the GET endpoints) the default Plone implementation. The serialization of tiles didn’t match the Mosaic (and plone.app.blocks) implementation and it’s done to not rely on those technologies. The serialization of the tile information on objects are subject to change in the future to extend or improve features.

A tile in Plone is an HTML snippet that can contain arbitrary content (e.g. text, images, videos).

Listing available tiles¶

Note

This endpoint currently does not return any data. The functionality needs to be implemented.

List all available tiles type by sending a GET request to the @tiles endpoint on the portal root:

GET /plone/@tiles HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

The server responds with a Status 200 and list all available tiles:

HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "@id": "http://localhost:55001/plone/@tiles/title",
    "title": "Title tile",
    "description": "A field tile that will show the title of the content object",
  },
  {
    "@id": "http://localhost:55001/plone/@tiles/description",
    "title": "Description tile",
    "description": "A field tile that will show the description of the content object",
  },
]

Retrieve JSON schema of an individual tile¶

Note

This endpoint currently does not return any data. The functionality needs to be implemented.

Retrieve the JSON schema of a specific tile by calling the ‘@tiles’ endpoint with the id of the tile:

GET /plone/@tiles/title HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

The server responds with a JSON schema definition for that particular tile:

HTTP/1.1 200 OK
Content-Type: application/json+schema

{
  "properties": {
    "title": {
      "description": "",
      "title": "Title",
      "type": "string"
    },
    ...
  },
  "required": [
    "title",
  ],
  "title": "Title Tile",
  "type": "object"
}

Retrieving tiles on a content object¶

Tiles data are stored in the objects via a Dexterity behavior plone.tiles. It has two attributes that stores existing tiles in the object (tiles) and the current layout (tiles_layout). As it’s a dexterity behavior, both attributes will be returned in a simple GET:

GET /plone/my-document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

The server responds with a Status 200 and list all stored tiles on that content object:

GET /plone/my-document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/my-document",
  ...
  "tiles_layout": [
    "#title-1",
    "#description-1",
    "#image-1"
  ],
  "tiles": {
    "#title-1": {
      "@type": "title"
    },
    "#description-1": {
      "@type": "Description"
    },
    "#image-1": {
      "@type": "Image",
      "image": "<some random url>"
    }
  }
}

Tiles objects will contain the tile metadata and the information to render it.

Adding tiles to an object¶

Storing tiles is done also via a default PATCH content operation:

PATCH /plone/my-document HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
  "tiles_layout": [
    "#title-1",
    "#description-1",
    "#image-1"
  ],
  "tiles": {
    "#title-1": {
      "@type": "title"
    },
    "#description-1": {
      "@type": "Description"
    },
    "#image-1": {
      "@type": "Image",
      "image": "<some random url>"
    }
  }
}

If the tile has been added, the server responds with a 204 status code.

Proposal on saving tiles layout¶

Note

This is not implemented (yet) in the tiles_layout field, but it’s a proposal on how could look like in the future. For now, we stick with the implementation shown in previous sections.

They might be serialized using this structure:

[
  [
    id: UUID,
    columns: [
      {
        id: UUID, // column UUID
        size: int // the size of the column
        rows: [
          {
            id: UUID, // inner row UUID
            cells: [
              {
                id: UUID, // cell UUID
                component: string
                content: {
                  // tile fields serialization (or tile id referal)
                },
                size: int
              },
            ]
          }
        ]
      },
    ]
  ], // row 1
  [], // row 2
]

It tries to match the usual way of CSS frameworks to map grid systems. So we have:

row (orderables up/down) -> column (resizables on width) -> row -> cell (actual tile content)

Rows are orderable vertically, columns resizables horizontally and cells can be moved around to an specific inner row.

Querystring¶

The @querystring endpoint returns the querystring config of plone.app.querystring.

Instead of simply exposing the querystring related field and operation entries from the registry, it serializes them the same way the @@querybuilderjsonconfig view from p.a.querystring does.

This form is structured in a more conventient way for frontends to process:

Vocabularies will be resolved, and their values will be inlined in the values property
Operations will be inlined as well. The operations property will contain the list of operations (dotted names), and the operators property will contain the full definition of each of those operations supported by that field.
Indexes that are flagged as sortable are listed in a dedicated top-level property sortable_indexes

Available options for the querystring in a Plone site can be queried by interacting with the /@querystring endpoint on portal root:

Querystring Config¶

To retrieve all querystring options in the portal, call the /@querystring endpoint with a GET request:

http

GET /plone/@querystring HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@querystring -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/@querystring Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/@querystring', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

The server will respond with all querystring options in the portal:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@querystring", 
  "indexes": {
    "Creator": {
      "description": "The person that created an item", 
      "enabled": true, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.string.currentUser", 
        "plone.app.querystring.operation.selection.any"
      ], 
      "operators": {
        "plone.app.querystring.operation.selection.any": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Matches any of", 
          "widget": "MultipleSelectionWidget"
        }, 
        "plone.app.querystring.operation.string.currentUser": {
          "description": "The user viewing the querystring results", 
          "operation": "plone.app.querystring.queryparser._currentUser", 
          "title": "Current logged in user", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Creator", 
      "values": {}, 
      "vocabulary": "plone.app.vocabularies.Users"
    }, 
    "Description": {
      "description": "An item's description", 
      "enabled": true, 
      "group": "Text", 
      "operations": [
        "plone.app.querystring.operation.string.contains"
      ], 
      "operators": {
        "plone.app.querystring.operation.string.contains": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Contains", 
          "widget": "StringWidget"
        }
      }, 
      "sortable": false, 
      "title": "Description", 
      "values": {}, 
      "vocabulary": null
    }, 
    "SearchableText": {
      "description": "Text search of an item's contents", 
      "enabled": true, 
      "group": "Text", 
      "operations": [
        "plone.app.querystring.operation.string.contains"
      ], 
      "operators": {
        "plone.app.querystring.operation.string.contains": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Contains", 
          "widget": "StringWidget"
        }
      }, 
      "sortable": false, 
      "title": "Searchable text", 
      "values": {}, 
      "vocabulary": null
    }, 
    "Subject": {
      "description": "Tags are used for organization of content", 
      "enabled": true, 
      "group": "Text", 
      "operations": [
        "plone.app.querystring.operation.selection.any", 
        "plone.app.querystring.operation.selection.all"
      ], 
      "operators": {
        "plone.app.querystring.operation.selection.all": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._all", 
          "title": "Matches all of", 
          "widget": "MultipleSelectionWidget"
        }, 
        "plone.app.querystring.operation.selection.any": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Matches any of", 
          "widget": "MultipleSelectionWidget"
        }
      }, 
      "sortable": false, 
      "title": "Tag", 
      "values": {}, 
      "vocabulary": "plone.app.vocabularies.Keywords"
    }, 
    "Title": {
      "description": "Text search of an item's title", 
      "enabled": true, 
      "group": "Text", 
      "operations": [
        "plone.app.querystring.operation.string.contains"
      ], 
      "operators": {
        "plone.app.querystring.operation.string.contains": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Contains", 
          "widget": "StringWidget"
        }
      }, 
      "sortable": false, 
      "title": "Title", 
      "values": {}, 
      "vocabulary": null
    }, 
    "created": {
      "description": "The date an item was created", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Creation date", 
      "values": {}, 
      "vocabulary": null
    }, 
    "effective": {
      "description": "The time and date an item was first published", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Effective date", 
      "values": {}, 
      "vocabulary": null
    }, 
    "effectiveRange": {
      "description": "Querying this is undefined", 
      "enabled": false, 
      "group": "Dates", 
      "operations": [], 
      "operators": {}, 
      "sortable": false, 
      "title": "Effective range", 
      "values": {}, 
      "vocabulary": null
    }, 
    "end": {
      "description": "The end date and time of an event", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Event end date", 
      "values": {}, 
      "vocabulary": null
    }, 
    "expires": {
      "description": "The time and date an item was expired", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Expiration date", 
      "values": {}, 
      "vocabulary": null
    }, 
    "getId": {
      "description": "The short name of an item (used in the url)", 
      "enabled": true, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.string.is"
      ], 
      "operators": {
        "plone.app.querystring.operation.string.is": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._equal", 
          "title": "Is", 
          "widget": "StringWidget"
        }
      }, 
      "sortable": true, 
      "title": "Short name (id)", 
      "values": {}, 
      "vocabulary": null
    }, 
    "getObjPositionInParent": {
      "description": "The order of an item in its parent folder", 
      "enabled": false, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.int.is", 
        "plone.app.querystring.operation.int.lessThan", 
        "plone.app.querystring.operation.int.largerThan"
      ], 
      "operators": {
        "plone.app.querystring.operation.int.is": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._intEqual", 
          "title": "Equals", 
          "widget": "StringWidget"
        }, 
        "plone.app.querystring.operation.int.largerThan": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._intLargerThan", 
          "title": "Larger than", 
          "widget": "StringWidget"
        }, 
        "plone.app.querystring.operation.int.lessThan": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._intLessThan", 
          "title": "Less than", 
          "widget": "StringWidget"
        }
      }, 
      "sortable": true, 
      "title": "Order in folder", 
      "values": {}, 
      "vocabulary": null
    }, 
    "getRawRelatedItems": {
      "description": "Find items related to the selected items", 
      "enabled": false, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.reference.is"
      ], 
      "operators": {
        "plone.app.querystring.operation.reference.is": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._referenceIs", 
          "title": "Equals", 
          "widget": "ReferenceWidget"
        }
      }, 
      "sortable": false, 
      "title": "Related To", 
      "values": {}, 
      "vocabulary": null
    }, 
    "isDefaultPage": {
      "description": "Find items that are the default view for their containing folder.", 
      "enabled": false, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.boolean.isTrue", 
        "plone.app.querystring.operation.boolean.isFalse"
      ], 
      "operators": {
        "plone.app.querystring.operation.boolean.isFalse": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._isFalse", 
          "title": "No", 
          "widget": null
        }, 
        "plone.app.querystring.operation.boolean.isTrue": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._isTrue", 
          "title": "Yes", 
          "widget": null
        }
      }, 
      "sortable": false, 
      "title": "Default Page", 
      "values": {}, 
      "vocabulary": null
    }, 
    "isFolderish": {
      "description": "Find items that can contain other objects", 
      "enabled": false, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.boolean.isTrue", 
        "plone.app.querystring.operation.boolean.isFalse"
      ], 
      "operators": {
        "plone.app.querystring.operation.boolean.isFalse": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._isFalse", 
          "title": "No", 
          "widget": null
        }, 
        "plone.app.querystring.operation.boolean.isTrue": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._isTrue", 
          "title": "Yes", 
          "widget": null
        }
      }, 
      "sortable": false, 
      "title": "Folder-like", 
      "values": {}, 
      "vocabulary": null
    }, 
    "modified": {
      "description": "The time and date an item was last modified", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Modification date", 
      "values": {}, 
      "vocabulary": null
    }, 
    "path": {
      "description": "The location of an item ", 
      "enabled": true, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.string.absolutePath", 
        "plone.app.querystring.operation.string.path", 
        "plone.app.querystring.operation.string.relativePath"
      ], 
      "operators": {
        "plone.app.querystring.operation.string.absolutePath": {
          "description": "Location in the site structure", 
          "operation": "plone.app.querystring.queryparser._absolutePath", 
          "title": "Absolute path", 
          "widget": "ReferenceWidget"
        }, 
        "plone.app.querystring.operation.string.path": {
          "description": "Location in the navigation structure", 
          "operation": "plone.app.querystring.queryparser._navigationPath", 
          "title": "Navigation path", 
          "widget": "ReferenceWidget"
        }, 
        "plone.app.querystring.operation.string.relativePath": {
          "description": "Use '../' to navigate to parent objects.", 
          "operation": "plone.app.querystring.queryparser._relativePath", 
          "title": "Relative path", 
          "widget": "RelativePathWidget"
        }
      }, 
      "sortable": false, 
      "title": "Location", 
      "values": {}, 
      "vocabulary": null
    }, 
    "portal_type": {
      "description": "An item's type (e.g. Event)", 
      "enabled": true, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.selection.any"
      ], 
      "operators": {
        "plone.app.querystring.operation.selection.any": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Matches any of", 
          "widget": "MultipleSelectionWidget"
        }
      }, 
      "sortable": false, 
      "title": "Type", 
      "values": {
        "ATTestDocument": {
          "title": "Test Document"
        }, 
        "ATTestFolder": {
          "title": "Test Folder"
        }, 
        "Collection": {
          "title": "Collection"
        }, 
        "DXTestDocument": {
          "title": "DX Test Document"
        }, 
        "Discussion Item": {
          "title": "Comment"
        }, 
        "Document": {
          "title": "Page"
        }, 
        "Event": {
          "title": "Event"
        }, 
        "File": {
          "title": "File"
        }, 
        "Folder": {
          "title": "Folder"
        }, 
        "Image": {
          "title": "Image"
        }, 
        "Link": {
          "title": "Link"
        }, 
        "News Item": {
          "title": "News Item"
        }
      }, 
      "vocabulary": "plone.app.vocabularies.ReallyUserFriendlyTypes"
    }, 
    "review_state": {
      "description": "An item's workflow state (e.g.published)", 
      "enabled": true, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.selection.any"
      ], 
      "operators": {
        "plone.app.querystring.operation.selection.any": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Matches any of", 
          "widget": "MultipleSelectionWidget"
        }
      }, 
      "sortable": true, 
      "title": "Review state", 
      "values": {
        "external": {
          "title": "Externally visible [external]"
        }, 
        "internal": {
          "title": "Internal draft [internal]"
        }, 
        "internally_published": {
          "title": "Internally published [internally_published]"
        }, 
        "pending": {
          "title": "Pending [pending]"
        }, 
        "private": {
          "title": "Private [private]"
        }, 
        "published": {
          "title": "Published with accent \u00e9 [published]"
        }, 
        "visible": {
          "title": "Public draft [visible]"
        }
      }, 
      "vocabulary": "plone.app.vocabularies.WorkflowStates"
    }, 
    "show_inactive": {
      "description": "Select which roles have the permission to view inactive objects", 
      "enabled": true, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.string.showInactive"
      ], 
      "operators": {
        "plone.app.querystring.operation.string.showInactive": {
          "description": "The user roles which are allowed to see inactive content", 
          "operation": "plone.app.querystring.queryparser._showInactive", 
          "title": "Show Inactive", 
          "widget": "MultipleSelectionWidget"
        }
      }, 
      "sortable": false, 
      "title": "Show Inactive", 
      "values": {
        "Anonymous": {
          "title": "Anonymous"
        }, 
        "Authenticated": {
          "title": "Authenticated"
        }, 
        "Contributor": {
          "title": "Contributor"
        }, 
        "Editor": {
          "title": "Editor"
        }, 
        "Manager": {
          "title": "Manager"
        }, 
        "Member": {
          "title": "Member"
        }, 
        "Owner": {
          "title": "Owner"
        }, 
        "Reader": {
          "title": "Reader"
        }, 
        "Reviewer": {
          "title": "Reviewer"
        }, 
        "Site Administrator": {
          "title": "Site Administrator"
        }
      }, 
      "vocabulary": "plone.app.vocabularies.Roles"
    }, 
    "sortable_title": {
      "description": "The item's title, transformed for sorting", 
      "enabled": false, 
      "group": "Text", 
      "operations": [
        "plone.app.querystring.operation.string.contains", 
        "plone.app.querystring.operation.string.is"
      ], 
      "operators": {
        "plone.app.querystring.operation.string.contains": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Contains", 
          "widget": "StringWidget"
        }, 
        "plone.app.querystring.operation.string.is": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._equal", 
          "title": "Is", 
          "widget": "StringWidget"
        }
      }, 
      "sortable": true, 
      "title": "Sortable Title", 
      "values": {}, 
      "vocabulary": null
    }, 
    "start": {
      "description": "The start date and time of an event", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Event start date", 
      "values": {}, 
      "vocabulary": null
    }
  }, 
  "sortable_indexes": {
    "Creator": {
      "description": "The person that created an item", 
      "enabled": true, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.string.currentUser", 
        "plone.app.querystring.operation.selection.any"
      ], 
      "operators": {
        "plone.app.querystring.operation.selection.any": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Matches any of", 
          "widget": "MultipleSelectionWidget"
        }, 
        "plone.app.querystring.operation.string.currentUser": {
          "description": "The user viewing the querystring results", 
          "operation": "plone.app.querystring.queryparser._currentUser", 
          "title": "Current logged in user", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Creator", 
      "values": {}, 
      "vocabulary": "plone.app.vocabularies.Users"
    }, 
    "created": {
      "description": "The date an item was created", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Creation date", 
      "values": {}, 
      "vocabulary": null
    }, 
    "effective": {
      "description": "The time and date an item was first published", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Effective date", 
      "values": {}, 
      "vocabulary": null
    }, 
    "end": {
      "description": "The end date and time of an event", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Event end date", 
      "values": {}, 
      "vocabulary": null
    }, 
    "expires": {
      "description": "The time and date an item was expired", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Expiration date", 
      "values": {}, 
      "vocabulary": null
    }, 
    "getId": {
      "description": "The short name of an item (used in the url)", 
      "enabled": true, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.string.is"
      ], 
      "operators": {
        "plone.app.querystring.operation.string.is": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._equal", 
          "title": "Is", 
          "widget": "StringWidget"
        }
      }, 
      "sortable": true, 
      "title": "Short name (id)", 
      "values": {}, 
      "vocabulary": null
    }, 
    "getObjPositionInParent": {
      "description": "The order of an item in its parent folder", 
      "enabled": false, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.int.is", 
        "plone.app.querystring.operation.int.lessThan", 
        "plone.app.querystring.operation.int.largerThan"
      ], 
      "operators": {
        "plone.app.querystring.operation.int.is": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._intEqual", 
          "title": "Equals", 
          "widget": "StringWidget"
        }, 
        "plone.app.querystring.operation.int.largerThan": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._intLargerThan", 
          "title": "Larger than", 
          "widget": "StringWidget"
        }, 
        "plone.app.querystring.operation.int.lessThan": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._intLessThan", 
          "title": "Less than", 
          "widget": "StringWidget"
        }
      }, 
      "sortable": true, 
      "title": "Order in folder", 
      "values": {}, 
      "vocabulary": null
    }, 
    "modified": {
      "description": "The time and date an item was last modified", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Modification date", 
      "values": {}, 
      "vocabulary": null
    }, 
    "review_state": {
      "description": "An item's workflow state (e.g.published)", 
      "enabled": true, 
      "group": "Metadata", 
      "operations": [
        "plone.app.querystring.operation.selection.any"
      ], 
      "operators": {
        "plone.app.querystring.operation.selection.any": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Matches any of", 
          "widget": "MultipleSelectionWidget"
        }
      }, 
      "sortable": true, 
      "title": "Review state", 
      "values": {
        "external": {
          "title": "Externally visible [external]"
        }, 
        "internal": {
          "title": "Internal draft [internal]"
        }, 
        "internally_published": {
          "title": "Internally published [internally_published]"
        }, 
        "pending": {
          "title": "Pending [pending]"
        }, 
        "private": {
          "title": "Private [private]"
        }, 
        "published": {
          "title": "Published with accent \u00e9 [published]"
        }, 
        "visible": {
          "title": "Public draft [visible]"
        }
      }, 
      "vocabulary": "plone.app.vocabularies.WorkflowStates"
    }, 
    "sortable_title": {
      "description": "The item's title, transformed for sorting", 
      "enabled": false, 
      "group": "Text", 
      "operations": [
        "plone.app.querystring.operation.string.contains", 
        "plone.app.querystring.operation.string.is"
      ], 
      "operators": {
        "plone.app.querystring.operation.string.contains": {
          "description": null, 
          "operation": "plone.app.querystring.queryparser._contains", 
          "title": "Contains", 
          "widget": "StringWidget"
        }, 
        "plone.app.querystring.operation.string.is": {
          "description": "Tip: you can use * to autocomplete.", 
          "operation": "plone.app.querystring.queryparser._equal", 
          "title": "Is", 
          "widget": "StringWidget"
        }
      }, 
      "sortable": true, 
      "title": "Sortable Title", 
      "values": {}, 
      "vocabulary": null
    }, 
    "start": {
      "description": "The start date and time of an event", 
      "enabled": true, 
      "group": "Dates", 
      "operations": [
        "plone.app.querystring.operation.date.lessThan", 
        "plone.app.querystring.operation.date.largerThan", 
        "plone.app.querystring.operation.date.between", 
        "plone.app.querystring.operation.date.lessThanRelativeDate", 
        "plone.app.querystring.operation.date.largerThanRelativeDate", 
        "plone.app.querystring.operation.date.today", 
        "plone.app.querystring.operation.date.beforeToday", 
        "plone.app.querystring.operation.date.afterToday", 
        "plone.app.querystring.operation.date.beforeRelativeDate", 
        "plone.app.querystring.operation.date.afterRelativeDate"
      ], 
      "operators": {
        "plone.app.querystring.operation.date.afterRelativeDate": {
          "description": "After N days in the future", 
          "operation": "plone.app.querystring.queryparser._afterRelativeDate", 
          "title": "After relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.afterToday": {
          "description": "After the current day", 
          "operation": "plone.app.querystring.queryparser._afterToday", 
          "title": "After today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.beforeRelativeDate": {
          "description": "Before N days in the past", 
          "operation": "plone.app.querystring.queryparser._beforeRelativeDate", 
          "title": "Before relative Date", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.beforeToday": {
          "description": "Before the current day", 
          "operation": "plone.app.querystring.queryparser._beforeToday", 
          "title": "Before today", 
          "widget": null
        }, 
        "plone.app.querystring.operation.date.between": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._between", 
          "title": "Between dates", 
          "widget": "DateRangeWidget"
        }, 
        "plone.app.querystring.operation.date.largerThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._largerThan", 
          "title": "After date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.largerThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._moreThanRelativeDate", 
          "title": "Within last", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThan": {
          "description": "Please use YYYY/MM/DD.", 
          "operation": "plone.app.querystring.queryparser._lessThan", 
          "title": "Before date", 
          "widget": "DateWidget"
        }, 
        "plone.app.querystring.operation.date.lessThanRelativeDate": {
          "description": "Please enter the number in days.", 
          "operation": "plone.app.querystring.queryparser._lessThanRelativeDate", 
          "title": "Within next", 
          "widget": "RelativeDateWidget"
        }, 
        "plone.app.querystring.operation.date.today": {
          "description": "The current day", 
          "operation": "plone.app.querystring.queryparser._today", 
          "title": "Today", 
          "widget": null
        }
      }, 
      "sortable": true, 
      "title": "Event start date", 
      "values": {}, 
      "vocabulary": null
    }
  }
}

Querystring Search¶

The @querystring-search endpoint given a p.a.querystring query returns the results.

You can call the /@querystring-search endpoint with a POST request and the p.a.querystring query in JSON BODY, along with the others querystring options:

http

POST /plone/@querystring-search HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "query": [
        {
            "i": "portal_type",
            "o": "plone.app.querystring.operation.selection.any",
            "v": [
                "Document"
            ]
        }
    ]
}

curl

curl -i -X POST http://nohost/plone/@querystring-search -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"query": [{"i": "portal_type", "o": "plone.app.querystring.operation.selection.any", "v": ["Document"]}]}' --user admin:secret

httpie

echo '{
  "query": [
    {
      "i": "portal_type",
      "o": "plone.app.querystring.operation.selection.any",
      "v": [
        "Document"
      ]
    }
  ]
}' | http POST http://nohost/plone/@querystring-search Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/@querystring-search', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'query': [{
        'i': 'portal_type',
        'o': 'plone.app.querystring.operation.selection.any',
        'v': ['Document'],
    }],
}, auth=('admin', 'secret'))

The server will respond with the results:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@querystring-search", 
  "items": [
    {
      "@id": "http://localhost:55001/plone/front-page", 
      "@type": "Document", 
      "description": "Congratulations! You have successfully installed Plone.", 
      "review_state": "private", 
      "title": "Welcome to Plone"
    }, 
    {
      "@id": "http://localhost:55001/plone/testdocument", 
      "@type": "Document", 
      "description": "", 
      "review_state": "private", 
      "title": "Test Document"
    }
  ], 
  "items_total": 2
}

The endpoint accepts the same parameters than the querystring search accept:

b_start

b_size

sort_on

sort_order

limit

and also the fullobjects parameter for return the whole objects instead of the summary serialization of them.

Customizing the API¶

Content serialization¶

Dexterity fields¶

The API automatically converts all field values to JSON compatible data, whenever possible. However, you might use fields which store data that cannot be automatically converted, or you might want to customize the representation of certain fields.

For extending or changing the serializing of certain dexterity fields you need to register an IFieldSerializer-adapter.

Example:

from plone.customfield.interfaces import ICustomField
from plone.dexterity.interfaces import IDexterityContent
from plone.restapi.interfaces import IFieldSerializer
from plone.restapi.serializer.converters import json_compatible
from plone.restapi.serializer.dxfields import DefaultFieldSerializer
from zope.component import adapter
from zope.interface import Interface
from zope.interface import implementer


@adapter(ICustomField, IDexterityContent, Interface)
@implementer(IFieldSerializer)
class CustomFieldSerializer(DefaultFieldSerializer):

    def __call__(self):
        value = self.get_value()
        if value is not None:
            # Do custom serializing here, e.g.:
            value = value.output()

        return json_compatible(value)

Register the adapter in ZCML:

<configure xmlns="http://namespaces.zope.org/zope">

    <adapter factory=".serializer.CustomFieldSerializer" />

</configure>

The json_compatible function recursively converts the value to JSON compatible data, when possible. When a value cannot be converted, a TypeError is raised. It is recommended to pass all values through json_compatible in order to validate and convert them.

For customizing a specific field instance, a named IFieldSerializer adapter can be registered. The name may either be the full dottedname of the field (plone.app.dexterity.behaviors.exclfromnav.IExcludeFromNavigation.exclude_from_nav) or the shortname of the field (exclude_from_nav).

Conventions¶

Nouns vs Verbs¶

Rule: Use nouns to represent resources.

Do:

/my-folder
/@registry
/@types

Don’t:

/createFolder
/deleteDocument
/updateEvent

Reason:

RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties as verbs do not. The REST architectural principle uses HTTP verbs to interact with resources.

Though, there is an exception to that rule, verbs can be used for specific actions or calculations, .e.g.:

/login
/logout
/move-to
/reset-password

Singluar vs Plural¶

Rule: Use plural resources.

Do:

/users
/users/21

Don’t:

/user
/user/21

Reason:

If you use singular for a collection like resource (e.g. “/user” to retrieve a list of all users) it feels wrong. Mixing singular and plural is confusing (e.g. user “/users” for retrieving users and “/user/21” to retrieve a single user).

Attribute names in URIs¶

Rule: Use hyphens to improve readability of URIs.

Do:

/users/noam/reset-password

Don’t:

/users/noam/resetPassword
/users/noam/ResetPassword
/users/noam/reset_password

Reason:

Upper vs. Lowercase¶

Rule: Use lowercase letters in URIs.

Do:

http://example.com/my-folder/my-document

Don’t:

http://example.com/My-Folder/My-Document

Reason: RFC 3986 defines URIs as case-sensitive except for the scheme and host components. e.g.

Those two URIs are equivalent:

http://example.org/my-folder/my-document
HTTP://EXAMPLE.ORG/my-folder/my-document

While this one is not equivalent to the two URIs above:

http://example.org/My-Folder/my-document

To avoid confusion we always use lowercase letters in URIs.

Versioning¶

Versioning APIs does make a lot of sense for public API services. Especially if an API provider needs to ship different versions of the API at the same time. Though, Plone already has a way to version packages and it currently does not make sense for us to expose that information via the API. We will always just ship one version of the API at a time and we are usually in full control over the backend and the frontend.

Translations¶

Note

This is only available on Plone 5.

Since Plone 5 the product plone.app.multilingual is included in the base Plone installation although it is not enabled by default.

Multilingualism in Plone not only allows the managers of the site to configure the site interface texts to be in one language or another (such as the configuration menus, error messages, information messages or other static text) but also to configure Plone to handle multilingual content. To achieve that it provides the user interface for managing content translations.

You can get additional information about the multilingual capabilities of Plone in the documentation.

In connection with that capabilities, plone.restapi provides a @translations endpoint to handle the translation information of the content objects.

Once we have installed plone.app.multilingual and enabled more than one language we can link two content-items of different languages to be the translation of each other issuing a POST query to the @translations endpoint including the id of the content which should be linked to. The id of the content must be a full URL of the content object:

http

POST /plone/en/test-document/@translations HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "id": "http://localhost:55001/plone/es/test-document"
}

curl

curl -i -X POST http://nohost/plone/en/test-document/@translations -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"id": "http://localhost:55001/plone/es/test-document"}' --user admin:secret

httpie

echo '{
  "id": "http://localhost:55001/plone/es/test-document"
}' | http POST http://nohost/plone/en/test-document/@translations Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.post('http://nohost/plone/en/test-document/@translations', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'id': 'http://localhost:55001/plone/es/test-document',
}, auth=('admin', 'secret'))

Note

“id” is a required field and needs to point to an existing content on the site.

The API will return a 201 Created response if the linking was successful.

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://localhost:55001/plone/en/test-document

{}

After linking the contents we can get the list of the translations of that content item by issuing a GET request on the @translations endpoint of that content item.:

http

GET /plone/en/test-document/@translations HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/en/test-document/@translations -H 'Accept: application/json' --user admin:secret

httpie

http http://nohost/plone/en/test-document/@translations Accept:application/json -a admin:secret

python-requests

requests.get('http://nohost/plone/en/test-document/@translations', headers={
    'Accept': 'application/json',
}, auth=('admin', 'secret'))

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/en/test-document/@translations", 
  "items": [
    {
      "@id": "http://localhost:55001/plone/es/test-document", 
      "language": "es"
    }
  ]
}

To unlink the content, issue a DELETE request on the @translations endpoint of the content item and provide the language code you want to unlink.:

http

DELETE /plone/en/test-document/@translations HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "language": "es"
}

curl

curl -i -X DELETE http://nohost/plone/en/test-document/@translations -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"language": "es"}' --user admin:secret

httpie

echo '{
  "language": "es"
}' | http DELETE http://nohost/plone/en/test-document/@translations Accept:application/json Content-Type:application/json -a admin:secret

python-requests

requests.delete('http://nohost/plone/en/test-document/@translations', headers={
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}, json={
    'language': 'es',
}, auth=('admin', 'secret'))

Note

“language” is a required field.

HTTP/1.1 204 No Content

Expansion¶

This endpoint can be used with the Expansion mechanism which allows to get additional information about a content item in one query, avoiding unnecesary requests.

If a simple GET request is done on the content item, a new entry will be shown on the @components entry with the URL of the @translations endpoint:

Email Send¶

Send Mail to Arbitrary Addresses¶

To send an email to an arbitrary e-mail address, send a POST request to the /@email-send endpoint that is available on the site root:

POST http://localhost:8080/Plone/@email-send
Accept: application/json
Content-Type: application/json

{
  'name': 'John Doe',
  'from': 'john@doe.com',
  'to': 'jane@doe.com',
  'subject': 'Hello!',
  'message': 'Just want to say hi.'
}

This endpoint is controlled via the Use mailhost services permission, the default one in Zope.

The ‘to’, ‘from’ and ‘message’ fields are required. The ‘subject’ and ‘name’ fields are optional.

The server will respond with status 204 No Content when the email has been sent successfully:

HTTP/1.1 204 No Content

i18n: internationalization of screen messages¶

Plone already provides user-interface translations using the plone.app.locales packages.

In plone.restapi we also use those translations where the end user needs to have those translated strings, this way the front-end work is easier, because you directly get from the server everything you need, instead of needing to query yet another endpoint to get the translations.

To do so, plone.restapi relies on Plone’s language-negotiation configuration and lets Plone to do the work of deciding the language in which the messages should be shown.

For the content of a multilingual site built using plone.app.multilingual this is an easy task: Plone is configured to show in the language of the content-object, so there is no need to ask anything to the REST API.

Nevertheless, when you want to query the Plone Site object of a multilingual site, or any other endpoint in a plain Plone site with multiple languages configured, you need to query the REST API which language do you want to have the messages on, otherwise you will get the messages on the default language configured in Plone.

To achieve that, the REST API requires to use the Accept-Language HTTP header passing as the value the code of the required language.

You will also need to configure Plone to use the browser request language negotiation. To do so, you need to go the Plone Control Panel, go to the Language Control Panel, open the Negotiation configuration tab and select “Use browser language request negotiation” option.

Using this option we can get the content-type titles translated:

http

GET /plone/@types HTTP/1.1
Accept: application/json
Accept-Language: es
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@types -H 'Accept: application/json' -H 'Accept-Language: es' --user admin:secret

httpie

http http://nohost/plone/@types Accept:application/json Accept-Language:es -a admin:secret

python-requests

requests.get('http://nohost/plone/@types', headers={
    'Accept': 'application/json',
    'Accept-Language': 'es',
}, auth=('admin', 'secret'))

And the response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@types/File", 
    "addable": true, 
    "title": "Archivo"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Folder", 
    "addable": true, 
    "title": "Carpeta"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Collection", 
    "addable": true, 
    "title": "Colecci\u00f3n"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/DXTestDocument", 
    "addable": true, 
    "title": "DX Test Document"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Link", 
    "addable": true, 
    "title": "Enlace"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Event", 
    "addable": true, 
    "title": "Evento"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Image", 
    "addable": true, 
    "title": "Imagen"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/News Item", 
    "addable": true, 
    "title": "Noticia"
  }, 
  {
    "@id": "http://localhost:55001/plone/@types/Document", 
    "addable": true, 
    "title": "P\u00e1gina"
  }
]

All the field titles and descriptions, will also be translated. For instance for the Folder content type:

http

GET /plone/@types/Folder HTTP/1.1
Accept: application/json
Accept-Language: es
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@types/Folder -H 'Accept: application/json' -H 'Accept-Language: es' --user admin:secret

httpie

http http://nohost/plone/@types/Folder Accept:application/json Accept-Language:es -a admin:secret

python-requests

requests.get('http://nohost/plone/@types/Folder', headers={
    'Accept': 'application/json',
    'Accept-Language': 'es',
}, auth=('admin', 'secret'))

And the response:

HTTP/1.1 200 OK
Content-Type: application/json+schema

{
  "fieldsets": [
    {
      "fields": [
        "title", 
        "description"
      ], 
      "id": "default", 
      "title": "Default"
    }, 
    {
      "fields": [
        "subjects", 
        "language", 
        "relatedItems"
      ], 
      "id": "categorization", 
      "title": "Categorizaci\u00f3n"
    }, 
    {
      "fields": [
        "effective", 
        "expires"
      ], 
      "id": "dates", 
      "title": "Fechas"
    }, 
    {
      "fields": [
        "creators", 
        "contributors", 
        "rights"
      ], 
      "id": "ownership", 
      "title": "Propiedad"
    }, 
    {
      "fields": [
        "allow_discussion", 
        "exclude_from_nav", 
        "id", 
        "nextPreviousEnabled"
      ], 
      "id": "settings", 
      "title": "Configuraci\u00f3n"
    }
  ], 
  "layouts": [
    "album_view", 
    "event_listing", 
    "full_view", 
    "listing_view", 
    "summary_view", 
    "tabular_view"
  ], 
  "properties": {
    "allow_discussion": {
      "choices": [
        [
          "True", 
          "S\u00ed"
        ], 
        [
          "False", 
          "No"
        ]
      ], 
      "description": "Permitir comentarios para este tipo de contenido", 
      "enum": [
        "True", 
        "False"
      ], 
      "enumNames": [
        "S\u00ed", 
        "No"
      ], 
      "title": "Permitir comentarios", 
      "type": "string", 
      "vocabulary": {
        "@id": "http://localhost:55001/plone/@sources/allow_discussion"
      }
    }, 
    "contributors": {
      "additionalItems": true, 
      "description": "Los nombres de las personas que han contribuido a este elemento. Cada colaborador deber\u00eda estar en una l\u00ednea independiente.", 
      "items": {
        "description": "", 
        "title": "", 
        "type": "string"
      }, 
      "title": "Colaboradores", 
      "type": "array", 
      "uniqueItems": true, 
      "widgetOptions": {
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Users"
        }
      }
    }, 
    "creators": {
      "additionalItems": true, 
      "description": "Personas responsables de la creaci\u00f3n del contenido de este elemento. Por favor, introduzca una lista de nombres de usuario, uno por l\u00ednea. El autor principal deber\u00eda ser el primero.", 
      "items": {
        "description": "", 
        "title": "", 
        "type": "string"
      }, 
      "title": "Creadores", 
      "type": "array", 
      "uniqueItems": true, 
      "widgetOptions": {
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Users"
        }
      }
    }, 
    "description": {
      "description": "Usado en listados de elementos y resultados de b\u00fasquedas.", 
      "minLength": 0, 
      "title": "Descripci\u00f3n", 
      "type": "string", 
      "widget": "textarea"
    }, 
    "effective": {
      "description": "La fecha en la que el documento ser\u00e1 publicado. Si no selecciona ninguna fecha, el documento ser\u00e1 publicado inmediatamente.", 
      "title": "Fecha de Publicaci\u00f3n", 
      "type": "string", 
      "widget": "datetime"
    }, 
    "exclude_from_nav": {
      "default": false, 
      "description": "Si est\u00e1 marcado, este elemento no aparecer\u00e1 en el \u00e1rbol de navegaci\u00f3n", 
      "title": "Excluir de la navegaci\u00f3n", 
      "type": "boolean"
    }, 
    "expires": {
      "description": "La fecha en la que expira el documento. Esto har\u00e1 autom\u00e1ticamente el documento invisible a otros a una fecha dada. Si no elije ninguna fecha, nunca expirar\u00e1.", 
      "title": "Fecha de Terminaci\u00f3n", 
      "type": "string", 
      "widget": "datetime"
    }, 
    "id": {
      "description": "Este nombre se mostrar\u00e1 en la URL.", 
      "title": "Nombre corto", 
      "type": "string"
    }, 
    "language": {
      "default": "en", 
      "description": "", 
      "title": "Idioma", 
      "type": "string", 
      "vocabulary": {
        "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.SupportedContentLanguages"
      }
    }, 
    "nextPreviousEnabled": {
      "default": false, 
      "description": "Esto habilita el widget siguiente/pr\u00f3ximo en los elementos contenidos en esta carpeta.", 
      "title": "Habilitar la navegaci\u00f3n siguiente/anterior", 
      "type": "boolean"
    }, 
    "relatedItems": {
      "additionalItems": true, 
      "default": [], 
      "description": "", 
      "items": {
        "description": "", 
        "title": "Related", 
        "type": "string", 
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Catalog"
        }
      }, 
      "title": "Contenido relacionado", 
      "type": "array", 
      "uniqueItems": true, 
      "widgetOptions": {
        "pattern_options": {
          "recentlyUsed": true
        }, 
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Catalog"
        }
      }
    }, 
    "rights": {
      "description": "Declaraci\u00f3n de copyright o informaci\u00f3n de otros derechos sobre este elemento.", 
      "minLength": 0, 
      "title": "Derechos de Autor", 
      "type": "string", 
      "widget": "textarea"
    }, 
    "subjects": {
      "additionalItems": true, 
      "description": "Las etiquetas suelen utilizarse para la organizaci\u00f3n a medida del contenido.", 
      "items": {
        "description": "", 
        "title": "", 
        "type": "string"
      }, 
      "title": "Etiquetas", 
      "type": "array", 
      "uniqueItems": true, 
      "widgetOptions": {
        "vocabulary": {
          "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Keywords"
        }
      }
    }, 
    "title": {
      "description": "", 
      "title": "T\u00edtulo", 
      "type": "string"
    }
  }, 
  "required": [
    "title", 
    "nextPreviousEnabled"
  ], 
  "title": "Carpeta", 
  "type": "object"
}

In a given object, the workflow state and actions will be translated too:

http

GET /plone/front-page/@workflow HTTP/1.1
Accept: application/json
Accept-Language: es
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/front-page/@workflow -H 'Accept: application/json' -H 'Accept-Language: es' --user admin:secret

httpie

http http://nohost/plone/front-page/@workflow Accept:application/json Accept-Language:es -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@workflow', headers={
    'Accept': 'application/json',
    'Accept-Language': 'es',
}, auth=('admin', 'secret'))

And the response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@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", 
      "title": "Privado"
    }
  ], 
  "transitions": [
    {
      "@id": "http://localhost:55001/plone/front-page/@workflow/publish", 
      "title": "Publicar"
    }, 
    {
      "@id": "http://localhost:55001/plone/front-page/@workflow/submit", 
      "title": "Enviar para publicaci\u00f3n"
    }
  ]
}

The same happens in the @history endpoint, all the relevant messages, will be shown translated:

http

GET /plone/front-page/@history HTTP/1.1
Accept: application/json
Accept-Language: es
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/front-page/@history -H 'Accept: application/json' -H 'Accept-Language: es' --user admin:secret

httpie

http http://nohost/plone/front-page/@history Accept:application/json Accept-Language:es -a admin:secret

python-requests

requests.get('http://nohost/plone/front-page/@history', headers={
    'Accept': 'application/json',
    'Accept-Language': 'es',
}, auth=('admin', 'secret'))

And the response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/front-page/@history/0", 
    "action": "Editado", 
    "actor": {
      "@id": "http://localhost:55001/plone/@users/test-user", 
      "fullname": "test-user", 
      "id": "test-user", 
      "username": null
    }, 
    "comments": "Versi\u00f3n inicial", 
    "may_revert": true, 
    "time": "1995-07-31T17:30:00", 
    "transition_title": "Editado", 
    "type": "versioning", 
    "version": 0
  }, 
  {
    "action": "Crear", 
    "actor": {
      "@id": "http://localhost:55001/plone/@users/test_user_1_", 
      "fullname": "", 
      "id": "test_user_1_", 
      "username": "test-user"
    }, 
    "comments": "", 
    "review_state": "private", 
    "state_title": "Privado", 
    "time": "1995-07-31T18:30:00", 
    "transition_title": "Crear", 
    "type": "workflow"
  }
]

Email Notification¶

Contact Site Owner aka Contact Form¶

Plone allows the user to contact the site owner via a form on the website. This makes sure the site owner does not have to expose their email addresses publicly and at the same time allow the users to reach out to the site owners.

To send an email notification to the site owner, send a POST request to the /@email-notification endpoint that is available on the site root:

POST http://localhost:8080/Plone/@email-notification
Accept: application/json
Content-Type: application/json

{
  'name': 'John Doe',
  'from': 'john@doe.com',
  'subject': 'Hello!',
  'message': 'Just want to say hi.'
}

The ‘from’ and ‘message’ fields are required. The ‘subject’ and ‘name’ fields are optional.

The server will respond with status 204 No Content when the email has been sent successfully:

HTTP/1.1 204 No Content

Contact Portal Users¶

Note

This endpoint is NOT implemented yet.

To send an email notification to another user of the portal, send a POST request to the /@email-notification endpoint on a particular user (e.g. the admin user):

POST http://localhost:8080/Plone/@users/admin/@email-notification
Accept: application/json
Content-Type: application/json

{
  'name': 'John Doe',
  'from': 'john@doe.com',
  'subject': 'Hello!',
  'message': 'Just want to say hi.'
}

Note

When using “email as login”, we strongly recommend to also enable the “Use UUID user ids” setting in the security control panel, to obfuscate the email in the user endpoint URL. Otherwise the ‘@users’ endpoint will expose the email addresses of all your users.

Upgrade Guide¶

This upgrade guide lists all breaking changes in plone.restapi and explains the necessary steps that are needed to upgrade to the lastest version.

Upgrading to plone.restapi 4.x¶

plone.restapi 4.0.0 introduces the following breaking changes:

Fields with vocabularies now return the token and title instead of the stored value.
Choice and list fields return a hyperlink to a vocabulary instead of choices, enum, and enumNames.
Serialize widget parameters into a widgetOptions object instead of adding them to the top level of the schema property.
The vocabularies endpoint does no longer returns an @id for terms, the results are batched, and terms are now listed as items instead of terms to match other batched responses.

Serialization and Deserialization of fields with vocabularies¶

The serialization of fields with vocabularies (e.g. Choice) now return the token and the title of the vocabulary term instead of the stored value. This is allows displaying the term (title) without additionally querying the vocabulary. However it’s necessary to adopt existing client implementations.

The date and time controlpanel previously returned a number for the first_weekday property:

{
  "@id": "http://localhost:55001/plone/@controlpanels/date-and-time",
  "data": {
      ...
      "first_weekday": 0,
      ...
  }
  ...
}

Now it returns an object with a token and a title:

{
  "@id": "http://localhost:55001/plone/@controlpanels/date-and-time",
  "data": {
      ...
      "first_weekday": {
          "title": "Monday",
          "token": "0"
      },
      ...
  }
  ...
}

Deserialization accepts objects that contain a token, but also just the token or the value.

However it’s highly recommended to always use the token as vocabulary terms may contain values that are not JSON serializable.

Choice and List fields return link to vocabulary instead of the values¶

Choice and List fields using named vocabularies are now serialized with a vocabulary property giving the URL of the @vocabularies endpoint for the vocabulary instead of including choices, enum and enumNames inline.

Old Response:

"choices": [
    [
        "de",
        "Deutsch"
    ],
    [
        "en",
        "English"
    ],
],
"enum": [
  "de",
  "en",
],
"enumNames": [
  "Deutsch",
  "English",
],

New response:

"vocabulary": {
    "@id": "http://localhost:55001/plone/@vocabularies/plone.app.discussion.vocabularies.CaptchaVocabulary"
},

Example: Vocabularies Subjects Field¶

The subjects field is now serialized as an array of string items using the plone.app.vocabularies.Keywords vocabulary.

Old response:

"subjects": {
  "choices": [...],
  "enum": [...],
  "enumNames": [...],
}
"type": "string"

New response:

"additionalItems": true,
"type": "array",
"uniqueItems": true,
"widgetOptions": {
    "vocabulary": {
      "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.Keywords"
  }
},
"items": {
  "description": "",
  "title": "",
  "type": "string"
},

Example: Available Time Zones Field (vocabulary in `items`)¶

Old response:

"available_timezones": {
  "additionalItems": true,
  "default": [],
  "description": "The timezones, which should be available for the portal. Can be set for users and events",
  "items": {
    "choices": [
      [
        "Africa/Abidjan",
        "Africa/Abidjan"
      ],
      [
        "Africa/Accra",
        "Africa/Accra"
      ],
      ...
    "enum": [
      ...
    ],
    "enumNames": [
      ...
    ]
  },
  title: "Available timezones",
  type: "array",
  uniqueItems: true,
}

New response:

"available_timezones": {
  "additionalItems": true,
  "default": [],
  "description": "The timezones, which should be available for the portal. Can be set for users and events",
  "items": {
    "description": "",
    "title": "",
    "type": "string",
    "vocabulary": {
      "@id": "http://localhost:8080/Plone/@vocabularies/plone.app.vocabularies.Timezones"
    }
  },
  "title": "Available timezones",
  "type": "array",
  "uniqueItems": true
},

Example: Weekday Field (vocabulary in main property)¶

Old response:

"first_weekday": {
  "choices": [
    [
      "0",
      "Monday"
    ],
    [
      "1",
      "Tuesday"
    ],
    [
      "2",
      "Wednesday"
    ],
    [
      "3",
      "Thursday"
    ],
    [
      "4",
      "Friday"
    ],
    [
      "5",
      "Saturday"
    ],
    [
      "6",
      "Sunday"
    ]
  ],
  "description": "First day in the week.",
  "enum": [
    "0",
    "1",
    "2",
    "3",
    "4",
    "5",
    "6"
  ],
  "enumNames": [
    "Monday",
    "Tuesday",
    "Wednesday",
    "Thursday",
    "Friday",
    "Saturday",
    "Sunday"
  ],
  "title": "First weekday",
  "type": "string"
},

New response:

"first_weekday": {
  "description": "First day in the week.",
  "title": "First weekday",
  "type": "string",
  "vocabulary": {
    "@id": "http://localhost:8080/Plone/@vocabularies/plone.app.vocabularies.Weekdays"
  }
},

Vocabularies Endpoint¶

The vocabularies endpoint does no longer returns an @id for terms.

The results are batched, and terms are now listed as items instead of terms to match other batched responses.

Batch size is 25 by default but can be overridden using the b_size parameter.

Old response:

{
  "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes",
  "terms": [
    {
      "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes/Collection",
      "title": "Collection",
      "token": "Collection"
    },
    ...
  ]
}

New response:

{
  "@id": "http://localhost:55001/plone/@vocabularies/plone.app.vocabularies.ReallyUserFriendlyTypes",
  "items": [
      {
        "title": "Collection",
        "token": "Collection"
      },
      ...
  ],
  "items_total": 12
}

Upgrading to plone.restapi 3.x¶

Image scales¶

Image download URLs and image scale URLs are created using the UID based url formats. This allows Plone to create different URLs when the image changes and thus ensuring caches are updated.

Old Response:

{
  "icon": {
    "download": "http://localhost:55001/plone/image/@@images/image/icon",
    "height": 32,
    "width": 24
  },
  "large": {
    "download": "http://localhost:55001/plone/image/@@images/image/large",
    "height": 768,
    "width": 576
  },
  ...
 }

New Response:

{
  "icon": {
    "download": "http://localhost:55001/plone/image/@@images/8eed3f80-5e1f-4115-85b8-650a10a6ca84.png",
    "height": 32,
    "width": 24
  },
  "large": {
    "download": "http://localhost:55001/plone/image/@@images/0d1824d1-2672-4b62-9277-aeb220d3bf15.png",
    "height": 768,
    "width": 576
  },
 ...
 }

Custom Content Deserializers¶

If you have implemented custom content deserializers, you have to handle the new create keyword in the __call__ method, which determines if deserialization is performed during object creation or while updating an object.

Deserializers should only fire an IObjectModifiedEvent event if an object has been updated. They should not fire it, when a new object has been created.

See Dexterity content deserializer for an example.

Upgrading to plone.restapi 2.x¶

plone.restapi 2.0.0 converts all datetime, DateTime and time to UTC before serializing. The translations endpoint becomes “expandable”, which introduces the following breaking changes.

Translations¶

When using the @translations endpoint in plone.restapi 1.x, the endpoint returned a language key with the content object’s language and a translations key with all its translations.

Now, as the endpoint is expandable we want the endpoint to behave like the other expandable endpoints. As top level information we only include the name of the endpoint on the @id attribute and the actual translations of the content object in an attribute called items.

This means that now the JSON response to a GET request to the Translations endpoint does not include anymore the language of the actual content item and the translations in an attribute called items instead of translations.

Old response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/en/test-document",
  "language": "en",
  "translations": [
    {
      "@id": "http://localhost:55001/plone/es/test-document",
      "language": "es"
    }
  ]
}

New response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/en/test-document/@translations",
  "items": [
    {
      "@id": "http://localhost:55001/plone/es/test-document",
      "language": "es"
    }
  ]
}

Upgrading to plone.restapi 1.0b1¶

In plone.restapi 1.0b1 the ‘url’ attribute on the Navigation and Breadcrumbs endpoint was renamed to ‘@id’ to be consistent with other links/URLs used in plone.restapi.

The JSON response to a GET request to the Breadcrumbs endpoint changed from using the ‘url’ attribute for ‘items’:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/front-page/@breadcrumbs",
  "items": [
    {
      "title": "Welcome to Plone",
      "url": "http://localhost:55001/plone/front-page"
    }
  ]
}

to using the ‘@id’ for the URL of ‘items’:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/front-page/@breadcrumbs",
  "items": [
    {
      "@id": "http://localhost:55001/plone/front-page",
      "title": "Welcome to Plone"
    }
  ]
}

The JSON response to a GET request to the Navigation endpoint changed from using the ‘url’ attribute for ‘items’:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/front-page/@navigation",
  "items": [
    {
      "title": "Home",
      "url": "http://localhost:55001/plone",
    },
    {
      "title": "Welcome to Plone",
      "url": "http://localhost:55001/plone/front-page"
    }
  ]
}

to using the ‘@id’ for the URL of ‘items’:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/front-page/@navigation",
  "items": [
    {
      "@id": "http://localhost:55001/plone",
      "title": "Home"
    },
    {
      "@id": "http://localhost:55001/plone/front-page",
      "title": "Welcome to Plone"
    }
  ]
}

The expansion mechanism is also affected by this change when Navigation or Breadcrumbs endpoints are expanded.

From using ‘url’ in the breadcrumb ‘items’:

{
  "@components": {
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/front-page/@breadcrumbs",
      "items": [
        {
          "title": "Welcome to Plone",
          "url": "http://localhost:55001/plone/front-page"
        }
      ]
    },
    "navigation": {
      "@id": "http://localhost:55001/plone/front-page/@navigation",
      "items": [
        {
          "title": "Home",
          "url": "http://localhost:55001/plone",
        },
        {
          "title": "Welcome to Plone",
          "url": "http://localhost:55001/plone/front-page"
        }
      ]
    },
    ...
}

to using ‘@id’ in the breadcrumb ‘items’:

{
  "@components": {
    "breadcrumbs": {
      "@id": "http://localhost:55001/plone/front-page/@breadcrumbs",
      "items": [
        {
          "@id": "http://localhost:55001/plone/front-page",
          "title": "Welcome to Plone"
        }
      ]
    },
    "navigation": {
      "@id": "http://localhost:55001/plone/front-page/@navigation",
      "items": [
        {
          "@id": "http://localhost:55001/plone",
          "title": "Home"
        },
        {
          "@id": "http://localhost:55001/plone/front-page",
          "title": "Welcome to Plone"
        }
      ]
    },
    ...
}

Changelog:

- Rename 'url' attribute on navigation / breadcrumb to '@id'. [timo]

Pull Request:

https://github.com/plone/plone.restapi/pull/459

Upgrading to plone.restapi 1.0a25¶

plone.restapi 1.0a25 introduced three breaking changes:

Remove @components navigation and breadcrumbs. Use top level @navigation and @breadcrumb endpoints instead. [timo]
Remove “sharing” attributes from GET response. [timo,jaroel]
Convert richtext using .output_relative_to. Direct conversion from RichText if no longer supported as we always need a context for the ITransformer. [jaroel]

Remove @components endpoint¶

plone.restapi 1.0a25 removed the @components endpoint which used to provide a Navigation and a Breadcrumbs endpoint.

Instead of using “@components/navigation”:

http://localhost:8080/Plone/@components/navigation

Use just “@navigation”:

http://localhost:8080/Plone/@navigation

Instead of using “@components/breadcrumbs”:

http://localhost:8080/Plone/@components/breadcrumbs

Use just “@breadcrumbs”:

http://localhost:8080/Plone/@breadcrumbs

Changelog:

- Remove @components navigation and breadcrumbs. Use top level @navigation and @breadcrumb endpoints instead. [timo]

Pull Request:

https://github.com/plone/plone.restapi/pull/425

Convert richtext using .output_relative_to¶

Using “.output_relative_to” in the

Changelog:

- Convert richtext using .output_relative_to. Direct conversion from RichText if no longer supported as we *always* need a context for the ITransformer. [jaroel]

Pull Request:

https://github.com/plone/plone.restapi/pull/428

Upgrading to plone.restapi 1.0a17¶

plone.restapi 1.0a17 changed the serialization of the rich-text “text” field for content objects from using ‘raw’ (a unicode string with the original input markup):

"text": {
  "content-type": "text/plain",
  "data": "Lorem ipsum",
  "encoding": "utf-8"
},

to using ‘output’ (a unicode object representing the transformed output):

"text": {
  "content-type": "text/plain",
  "data": "<p>Lorem ipsum</p>",
  "encoding": "utf-8"
},

Changelog:

- Change RichText field value to use 'output' instead of 'raw' to fix inline paths. This fixes #302. [erral]

Pull Request:

https://github.com/plone/plone.restapi/pull/346

Contributing to plone.restapi¶

Generating documentation examples¶

This documentation includes examples of requests and responses (http, curl, httpie and python-requests). These examples are generated by the documentation tests in test_documentation.py. To generate a new example, add a new test case to test_documentation.py - for example test_documentation_search_fullobjects, and run the test:

./bin/test -t test_documentation_search_fullobjects

This generates the request and the response files in tests/http-examples/.

Include them in the documentation like this:

..  http:example:: curl httpie python-requests
    :request: ../../src/plone/restapi/tests/http-examples/search_fullobjects.req

.. literalinclude:: ../../src/plone/restapi/tests/http-examples/search_fullobjects.resp
   :language: http

Build the sphinx docs locally to test the rendering by running ./bin/sphinxbuilder.

Make sure you add and commit the generated files in http-examples.

https://secure.travis-ci.org/plone/plone.restapi.png?branch=master

https://coveralls.io/repos/github/plone/plone.restapi/badge.svg?branch=master

https://readthedocs.org/projects/pip/badge

https://img.shields.io/pypi/v/plone.restapi.svg

Introduction¶

plone.restapi is a RESTful hypermedia API for Plone.

Documentation¶

http://plonerestapi.readthedocs.org

Getting started¶

A live demo of Plone 5 with the latest plone.restapi release is available at:

http://plonedemo.kitconcept.com

Example GET request on the portal root:

$ curl -i https://plonedemo.kitconcept.com -H "Accept: application/json"

Example POST request to create a new document:

$ curl -i -X POST https://plonedemo.kitconcept.com -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"@type": "Document", "title": "My Document"}' --user admin:admin

Note

You will need some kind of API browser application to explore the API. We recommend using Postman.

Installation¶

Install plone.restapi by adding it to your buildout:

[buildout]

...

eggs =
    plone.restapi

and then running bin/buildout

Contribute¶

Issue Tracker: https://github.com/plone/plone.restapi/issues
Source Code: https://github.com/plone/plone.restapi
Documentation: https://plonerestapi.readthedocs.io/en/latest

Examples¶

plone.restapi is used in production since the first alpha release. It can be seen in action at the following sites:

Zeelandia GmbH & Co. KG: https://www.zeelandia.de (by kitconcept GmbH)
VHS-Ehrenamtsportal: https://vhs-ehrenamtsportal.de (by kitconcept GmbH)
German Physical Society: https://www.dpg-physik.de (by kitconcept GmbH)
Universitat Politècnica de Catalunya: https://www.upc.edu (by kitconcept GmbH)

Support¶

If you are having issues, please let us know via the issue tracker.

If you required professional support, here is a list of Plone solution providers that contributed significantly to plone.restapi in the past:

kitconcept GmbH (Germany) https://kitconcept.com
4teamwork (Switzerland) https://www.4teamwork.ch
CodeSyntax (Spain) https://www.codesyntax.com/en

License¶

The project is licensed under the GPLv2.

Appendix, Indices and tables¶

HTTP Status Codes¶

This is the list of status codes that are used in plone.restapi. Here is a full list of all HTTP status codes.

200 OK: Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
201 Created: The request has been fulfilled and resulted in a new resource being created.
204 No Content: The server successfully processed the request, but is not returning any content. Usually used as a response to a successful delete request.
2xx Success: This class of status codes indicates the action requested by the client was received, understood, accepted and processed successfully.
400 Bad Request: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing)
401 Unauthorized: Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource.
403 Forbidden: The request was a valid request, but the server is refusing to respond to it. Unlike a 401 Unauthorized response, authenticating will make no difference.
404 Not Found: The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
405 Method Not Allowed: A request method is not supported for the requested resource; for example, a GET request on a form which requires data to be presented via POST, or a PUT request on a read-only resource.
409 Conflict: Indicates that the request could not be processed because of conflict in the request, such as an edit conflict in the case of multiple updates.
4xx Client Error: The 4xx class of status code is intended for cases in which the client seems to have errored.
500 Internal Server Error: The server failed to fulfill an apparently valid request.
5xx Server Error: The server failed to fulfill an apparently valid request.

Glossary¶

Accept Header: Part of the Request that is responsible to define the expected type of data to be accepted by the client in the Response.
Authentication Method: Access restriction provided by the connection chain to the server exposed to the client.
Authorization Header: Part of the Request that is responsible for the authentication related to the right user or service to ask for a Response.
Basic Auth: A simple Authentication Method referenced in the Authorization Header that needs to be provided by the server.
HTTP-Header
HTTP Header
Header: The part of the communication of the client with the server that provides the initialisation of the communication of a Request.
HTTP-Request
HTTP Request
Request
Requests: The initial action performed by a web client to communicate with a server. The Request is usually followed by a Response by the server, either synchronous or asynchronous (which is more complex to handle on the user side)
HTTP-Response
HTTP Response
Response: Answer of or action by the server that is executed or send to the client after the Request is processed.
HTTP-Verb
HTTP Verb
Verb: One of the basic actions that can be requested to be executed by the server (on an object) based on the Request.
Object URL: The target object of the Request
REST: REST stands for Representational State Transfer. It is a software architectural principle to create loosely coupled web APIs.
workflow: A concept in Plone (and other CMS’s) whereby a content object can be in a number of states (private, public, etcetera) and uses transitions to change between them (e.g. “publish”, “approve”, “reject”, “retract”). See the Plone docs on Workflow

Index

plone.restapi: A RESTful hypermedia API for Plone.¶

Contents¶

Introduction¶

Content Negotiation¶

Plone Content¶

Plone Portal Root:¶

Plone Folder:¶

Plone Document:¶

News Item:¶

Event:¶

Image:¶

File:¶

Link:¶

Collection:¶

Authentication¶

JSON Web Tokens (JWT)¶

Acquiring a token (@login)¶

Authenticating with a token¶

Renewing a token (@login-renew)¶

Invalidating a token (@logout)¶

Permissions¶

Explore the API using Postman¶

Configuration¶

Usage¶

Content Manipulation¶

Creating a Resource with POST¶

Successful Response (201 Created)¶

Unsuccessful Response (400 Bad Request)¶

Unsuccessful Response (500 Internal Server Error)¶

Possible POST Responses¶

POST Implementation¶

Reading a Resource with GET¶

Successful Response (200 OK)¶

Unsuccessful response (404 Not Found)¶

GET Implementation¶

GET Responses¶

Updating a Resource with PATCH¶

Successful Response (204 No Content)¶

Successful Response (200 OK)¶

Replacing a Resource with PUT¶

Successful Update (204 No Content)¶

Unsuccessful Update (409 Conflict)¶

PUT Implementation¶

PUT Responses¶

POST vs. PUT¶

Removing a Resource with DELETE¶

DELETE Implementation¶

DELETE Responses¶

Reordering sub resources¶

History¶

Listing the History of a Content Object¶

Get a Historical Version¶

Revert to a Historical Version¶

Batching¶

Top-level attributes¶

Batching links¶

Parameters¶

Comments¶

Listing Comments¶

Adding a Comment¶

Replying to a Comment¶

Updating a Comment¶

Deleting a Comment¶

Copy / Move¶

Copying an object¶

Moving an object¶

Copying/moving multiple objects¶

Expansion¶

Portal Actions¶

Listing available actions¶

Workflow¶

Locking¶

Locking an object¶

Unlocking an object¶

Refreshing a lock¶

Getting lock information¶

Updating a locked object¶

Sharing¶

Retrieving Local Roles¶

Searching for principals¶