API

This part of the documentation covers all resources (routes) provided by plone.jsonapi.routes. It also covers all the request parameters that can be applied to these resources to refine the results.

Concept

The API aims to be as fast as possible. So the concept of the API is to postpone expensive operations until the user really requests it. To do so, the API was built with a two step architecture.

An expensive operation is basically given, when the API needs to wake up an object to retrieve all its field values.

The two step architecture retrieves only the fields of the catalog results in the first step. Only if the user requests the API URL of a specific object, the object will be loaded and all the fields of the object will be returned.

Note

Since version 0.3, you can add a complete=yes paramter to bypass the two step behavior and retrieve the full object data immediately.

Base URL

After installation, the Plone API routes are available below the plone.jsonapi.core root URL (@@API) with the base /plone/api/1.0.

Example: http://localhost:8080/Plone/@@API/plone/api/1.0/api.json

Note

Please see the documentation of plone.jsonapi.core for the root URL.

There is also an overview of the registered routes, e.g.

http://localhost:8080/Plone/@@API/plone/api/1.0/api.json

Operations

The API understands the basic CRUD operations on the content resources. Only the VIEW operation is accessible via a HTTP GET request. All other operations have to be sent via a HTTP POST request.

OPERATION	URL	METHOD
VIEW	<BASE URL>/<RESOURCE>/<uid:optional>	GET
CREATE	<BASE URL>/<RESOURCE>/create/<uid:optional>	POST
UPDATE	<BASE URL>/<RESOURCE>/update/<uid:optional>	POST
DELETE	<BASE URL>/<RESOURCE>/delete/<uid:optional>	POST

Resources

URL Schema:<BASE URL>/<RESOURCE>/<OPERATION>/<uid:optional>

The API registers the routes to the resources during the Plone startup process. Each of the following resources is bound to a distinct portal type within Plone. So the folders resource will only return content informations of Folders.

Resource	Description
folders	Resource for all Folder contents
documents	Resource for all Page contents
events	Resource for all Event contents
files	Resource for all File contents
images	Resource for all Image contents
links	Resource for all Link contents
newsitems	Resource for all News Item contents
topics	Resource for all Collection (old style) contents
collections	Resource for all Collection contents

Note

Please see the section Parameters on how to refine the returned results

Special Resources

URL Schema:<BASE URL>/<RESOURCE>/<ACTION:optional>

Beside the content resources, there are some special resources available.

Resource	Action	Description
users	<username>,current	Resource for Plone Users
search		Search over all standard content types
version		Get the current Version
auth		Basic Authentication
login		Login with __ac_name and __ac_password

Parameters

URL Schema:<BASE URL>/<RESOURCE>?<KEY>=<VALUE>&<KEY>=<VALUE>

All content resources accept to be filtered by request parameters.

Key	Value	Description
q	searchterm	Search the SearchableText index for the given query string
path	/physical/path	Specifiy a physical path to only return results below it. See how to Query by path in the Plone docs for details.
depth	0..n	Specify the depth of a path query. Only relevant when using the path parameter.
limit	1..n	Limit the results to the given limit number. This will return batched results with x pages and n items per page
sort_on	catalog index	Sort the results by the given index
sort_order	asc / desc	Sort ascending or descending (default: ascending)
sort_limit	1..n	Limit the result set to n items. The portal catalog will only return n items.
complete	yes/y/1/True	Flag to return the full object results immediately. Bypasses the two step behavior of the API
children	yes/y/1/True	Flag to return the folder contents of a folder below the children key Only visible if complete flag is true or if an UID is provided
recent_created	today, yesterday this-week, this-month this-year	Specify a recent created date range, to find all items created within this date range until today. This uses internally ‘range’: ‘min’ query.
recent_modified	today, yesterday this-week, this-month this-year	Specify a recent modified date range, to find all items modified within this date range until today. This uses internally ‘range’: ‘min’ query.

Using Plone Indexes

It is also possible to use the Plone catalog indexes directly as request parameters.

New in version 0.4: Support for DateIndex, KeywordIndex and BooleanIndex. Support for ‘recent_modified’ and ‘recent_created’ literals.

Note

Custom added indexes can also be used, as long as they accept a single string value as query.

Query Records

It is also possible to use the ZPublisher query record format.

Example

http://localhost:8080/Plone/@@API/plone/api/1.0/folders?created.query:record:list:date=2015-01-02&created.range:record=min

New in version 0.5: Support for ZPublisher query record format added.

Response Format

The response format is for all resources the same.

{
    count: 1, // number of found items
    pagesize: 25, // items per page
    items: [  // List of all item objexts
        {
            id: "front-page", // item data
            ...
        }
    ],
    page: 1, // current page
    _runtime: 0.00381,  // calculation time to generate the data
    next: null,  // URL to the next batch
    pages: 1,  //  number of total pages
    previous: null  // URL to the previous batch
}

count

The number of found items – can be more than displayed on one site

pagesize

Number of items per page

items

List of found items – only catalog brain keys unless you add a complete=yes parameter to the request or request an URL with an UID at the end.

page

The current page of the batched result set

_runtime

The time in milliseconds needed to generate the data

next

The URL to the next batch

pages

The number of pages in the batch

previous

The URL to the previous batch

The API Module

import:from plone.jsonapi.routes import api doc:Provides core functionality to all other modules

plone.jsonapi.routes.api.copy_items(portal_type=None, request=None, uid=None, endpoint=None)

copy items

plone.jsonapi.routes.api.create_items(portal_type=None, request=None, uid=None, endpoint=None)

create items

1. If the uid is given, get the object and create the content in there (assumed that it is folderish)

2. If the uid is 0, the target folder is assumed the portal.

3. If there is no uid given, the payload is checked for either a key

   • parent_uid specifies the uid of the target folder
   • parent_path specifies the physical path of the target folder

plone.jsonapi.routes.api.create_object(**kw)

Creates an object

Returns:The new created content object Return type:object

plone.jsonapi.routes.api.create_object_in_container(container, portal_type, id=None, title=None)

Creates a content object in the specified container

Parameters:

• container (ATContentType/DexterityContentType/CatalogBrain) – A single folderish catalog brain or content object
• portal_type (string) – The portal type to create

Returns:

The new content object

Return type:

object

plone.jsonapi.routes.api.cut_items(portal_type=None, request=None, uid=None, endpoint=None)

cut items

plone.jsonapi.routes.api.delete_items(portal_type=None, request=None, uid=None, endpoint=None)

delete items

1. If the uid is given, we can ignore the request body and delete the object with the given uid (if the uid was valid).
2. If no uid is given, the user wants to delete more than one item. => go through each item and extract the uid. Delete it afterwards. // we should do this kind of transaction base. So if we can not get an // object for an uid, no item will be deleted.
3. we could check if the portal_type matches, just to be sure the user wants to delete the right content.

plone.jsonapi.routes.api.delete_object(brain_or_object)

Delete the given object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:Nothing Return type:None

plone.jsonapi.routes.api.do_action_for(brain_or_object, transition)

Perform a workflow transition

Parameters:

• brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object
• transition (string) – The workflow transition to perform, e.g. publish

Returns:

Nothing

Return type:

None

plone.jsonapi.routes.api.find_objects(uid=None)

Find the object by its UID

1. get the object from the given uid
2. fetch objects specified in the request parameters
3. fetch objects located in the request body

Parameters:uid (string) – The UID of the object to find Returns:List of found objects Return type:list

plone.jsonapi.routes.api.find_target_container(record)

Locates a target container for the given record

Parameters:record (dict) – The dictionary representation of a content object Returns:folder which contains the object Return type:object

plone.jsonapi.routes.api.get_batch(sequence, size, start=0, endpoint=None, complete=False)

create a batched result record out of a sequence (catalog brains)

plone.jsonapi.routes.api.get_batched(portal_type=None, request=None, uid=None, endpoint=None)

returns a batched result record (dictionary)

plone.jsonapi.routes.api.get_children_info(brain_or_object, complete=False)

Generate data items of the contained contents

Parameters:

• brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object
• complete (bool) – Flag to wake up the object and fetch all data

Returns:

info mapping of contained content items

Return type:

list

plone.jsonapi.routes.api.get_contents(brain_or_object, depth=1)

Lookup folder contents for this object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:List of contained contents Return type:list/Products.ZCatalog.Lazy.LazyMap

plone.jsonapi.routes.api.get_current_user()

Get the current logged in user

Returns:Member Return type:object

plone.jsonapi.routes.api.get_endpoint(brain_or_object)

Calculate the endpoint for this object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:Endpoint for this object (pluralized portal type) Return type:string

plone.jsonapi.routes.api.get_id(brain_or_object)

Get the Plone ID for this object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:Plone ID Return type:string

plone.jsonapi.routes.api.get_info(brain_or_object, endpoint=None, complete=False)

Extract the data from the catalog brain or object

Parameters:

• brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object
• endpoint (str/unicode) – The named URL endpoint for the root of the items
• complete (bool) – Flag to wake up the object and fetch all data

Returns:

Data mapping for the object/catalog brain

Return type:

dict

plone.jsonapi.routes.api.get_items(portal_type=None, request=None, uid=None, endpoint=None)

returns a list of items

1. If the UID is given, fetch the object directly => should return 1 item
2. If no UID is given, search for all items of the given portal_type

plone.jsonapi.routes.api.get_locally_allowed_types(brain_or_object)

Checks if the passed in object is folderish

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:A list of locally allowed content types Return type:list

plone.jsonapi.routes.api.get_object(brain_or_object)

Get the full content object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:Content object Return type:object

plone.jsonapi.routes.api.get_object_by_path(path)

Find an object by a given physical path

Parameters:path (string) – The physical path of the object to find Returns:Found Object or None Return type:object

plone.jsonapi.routes.api.get_object_by_record(record)

Find an object by a given record

Inspects request the record to locate an object

Parameters:record (dict) – A dictionary representation of an object Returns:Found Object or None Return type:object

plone.jsonapi.routes.api.get_object_by_request()

Find an object by request parameters

Inspects request parameters to locate an object

Returns:Found Object or None Return type:object

plone.jsonapi.routes.api.get_object_by_uid(uid)

Find an object by a given UID

Parameters:uid (string) – The UID of the object to find Returns:Found Object or None Return type:object

plone.jsonapi.routes.api.get_parent(brain_or_object)

Locate the parent object of the content/catalog brain

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:parent object Return type:ATContentType/DexterityContentType/PloneSite/CatalogBrain

plone.jsonapi.routes.api.get_parent_info(brain_or_object, endpoint=None)

Generate url information for the parent object

Parameters:

• brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object
• endpoint (str/unicode) – The named URL endpoint for the root of the items

Returns:

URL information mapping

Return type:

dict

plone.jsonapi.routes.api.get_parent_path(brain_or_object)

Calculate the physical parent path of this object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:Physical path of the parent object Return type:string

plone.jsonapi.routes.api.get_path(brain_or_object)

Calculate the physical path of this object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:Physical path of the object Return type:string

plone.jsonapi.routes.api.get_portal()

Get the portal object

Returns:Portal object Return type:object

plone.jsonapi.routes.api.get_portal_catalog()

Get the portal catalog tool

Returns:Portal Catalog Tool Return type:object

plone.jsonapi.routes.api.get_portal_reference_catalog()

Get the portal reference catalog tool

Returns:Portal Reference Catalog Tool Return type:object

plone.jsonapi.routes.api.get_portal_type(brain_or_object)

Get the portal type for this object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:Portal type Return type:string

plone.jsonapi.routes.api.get_portal_workflow()

Get the portal workflow tool

Returns:Portal Workflow Tool Return type:object

plone.jsonapi.routes.api.get_record(uid=None)

returns a single record

plone.jsonapi.routes.api.get_search_results(**kw)

Search the catalog and return the results

Returns:Catalog search results Return type:list/Products.ZCatalog.Lazy.LazyMap

plone.jsonapi.routes.api.get_tool(name)

Get a portal tool by name

Parameters:name (string) – The name of the tool, e.g. portal_catalog Returns:Portal Tool Return type:object

plone.jsonapi.routes.api.get_uid(brain_or_object)

Get the Plone UID for this object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:Plone UID Return type:string

plone.jsonapi.routes.api.get_url(brain_or_object)

Get the absolute Plone URL for this object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:Plone URL Return type:string

plone.jsonapi.routes.api.get_url_info(brain_or_object, endpoint=None)

Generate url information for the content object/catalog brain

Parameters:

• brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object
• endpoint (str/unicode) – The named URL endpoint for the root of the items

Returns:

URL information mapping

Return type:

dict

plone.jsonapi.routes.api.get_workflow_info(brain_or_object, endpoint=None)

Generate workflow information of the (first) assigned workflow

Parameters:

• brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object
• endpoint (str/unicode) – The named URL endpoint for the root of the items

Returns:

Workflow information mapping

Return type:

dict

plone.jsonapi.routes.api.is_brain(brain_or_object)

Checks if the passed in object is a portal catalog brain

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:True if the object is a catalog brain Return type:bool

plone.jsonapi.routes.api.is_folderish(brain_or_object)

Checks if the passed in object is folderish

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:True if the object is folderish Return type:bool

plone.jsonapi.routes.api.is_root(brain_or_object)

Checks if the passed in object is the portal root object

Parameters:brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object Returns:True if the object is the portal root object Return type:bool

plone.jsonapi.routes.api.make_items_for(brains_or_objects, endpoint=None, complete=False)

Generate API compatible data items for the given list of brains/objects

Parameters:

• brains_or_objects (list/Products.ZCatalog.Lazy.LazyMap) – List of objects or brains
• endpoint (str/unicode) – The named URL endpoint for the root of the items
• complete (bool) – Flag to wake up the object and fetch all data

Returns:

A list of extracted data items

Return type:

list

plone.jsonapi.routes.api.mkdir(path)

Crate a folder structure by a given path

Behavior is similar to mkdir -p

Parameters:path (string) – The physical path of the folder Returns:folder located at the path Return type:object

plone.jsonapi.routes.api.paste_items(portal_type=None, request=None, uid=None, endpoint=None)

paste items

plone.jsonapi.routes.api.update_items(portal_type=None, request=None, uid=None, endpoint=None)

update items

1. If the uid is given, the user wants to update the object with the data given in request body
2. If no uid is given, the user wants to update a bunch of objects. -> each record contains either an UID, path or parent_path + id

plone.jsonapi.routes.api.update_object_with_data(content, record)

Update the content with the record data

Parameters:

• content (ATContentType/DexterityContentType/CatalogBrain) – A single folderish catalog brain or content object
• record (dict) – The data to update

Returns:

The updated content object

Return type:

object

plone.jsonapi.routes.api.url_for(endpoint, **values)

Looks up the API URL for the given endpoint

Parameters:endpoint (string) – The name of the registered route (aka endpoint) Returns:External URL for this endpoint Return type:string/None