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)[source]

copy items

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

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)[source]

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)[source]

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)[source]

cut items

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

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

returns a batched result record (dictionary)

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

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)[source]

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()[source]

Get the current logged in user

Returns:Member
Return type:object
plone.jsonapi.routes.api.get_endpoint(brain_or_object)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Get the portal object

Returns:Portal object
Return type:object
plone.jsonapi.routes.api.get_portal_catalog()[source]

Get the portal catalog tool

Returns:Portal Catalog Tool
Return type:object
plone.jsonapi.routes.api.get_portal_reference_catalog()[source]

Get the portal reference catalog tool

Returns:Portal Reference Catalog Tool
Return type:object
plone.jsonapi.routes.api.get_portal_type(brain_or_object)[source]

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()[source]

Get the portal workflow tool

Returns:Portal Workflow Tool
Return type:object
plone.jsonapi.routes.api.get_record(uid=None)[source]

returns a single record

plone.jsonapi.routes.api.get_search_results(**kw)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

paste items

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

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)[source]

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)[source]

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

Table Of Contents

Previous topic

Quickstart

Next topic

Authentication

This Page