API — plone.jsonapi.routes 0.8.3 documentation

### Navigation

- index
- modules |
- next |
- previous |
- plone.jsonapi.routes 0.8.3 documentation »

# 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

### Navigation

- index
- modules |
- next |
- previous |
- plone.jsonapi.routes 0.8.3 documentation »