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.
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.
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
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 |
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
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 |
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. |
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.
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.
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
}
import: | from plone.jsonapi.routes import api |
---|---|
doc: | Provides core functionality to all other modules |
copy items
create items
If the uid is given, get the object and create the content in there (assumed that it is folderish)
If the uid is 0, the target folder is assumed the portal.
Creates an object
Returns: | The new created content object |
---|---|
Return type: | object |
Creates a content object in the specified container
Parameters: |
|
---|---|
Returns: | The new content object |
Return type: | object |
cut items
delete items
Delete the given object
Parameters: | brain_or_object (ATContentType/DexterityContentType/CatalogBrain) – A single catalog brain or content object |
---|---|
Returns: | Nothing |
Return type: | None |
Perform a workflow transition
Parameters: |
|
---|---|
Returns: | Nothing |
Return type: | None |
Find the object by its UID
Parameters: | uid (string) – The UID of the object to find |
---|---|
Returns: | List of found objects |
Return type: | list |
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 |
create a batched result record out of a sequence (catalog brains)
returns a batched result record (dictionary)
Generate data items of the contained contents
Parameters: |
|
---|---|
Returns: | info mapping of contained content items |
Return type: | list |
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 |
Get the current logged in user
Returns: | Member |
---|---|
Return type: | 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 |
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 |
Extract the data from the catalog brain or object
Parameters: |
|
---|---|
Returns: | Data mapping for the object/catalog brain |
Return type: | dict |
returns a list of items
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 |
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 |
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 |
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 |
Find an object by request parameters
Inspects request parameters to locate an object
Returns: | Found Object or None |
---|---|
Return type: | object |
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 |
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 |
Generate url information for the parent object
Parameters: |
|
---|---|
Returns: | URL information mapping |
Return type: | dict |
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 |
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 |
Get the portal object
Returns: | Portal object |
---|---|
Return type: | object |
Get the portal catalog tool
Returns: | Portal Catalog Tool |
---|---|
Return type: | object |
Get the portal reference catalog tool
Returns: | Portal Reference Catalog Tool |
---|---|
Return type: | 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 |
Get the portal workflow tool
Returns: | Portal Workflow Tool |
---|---|
Return type: | object |
Search the catalog and return the results
Returns: | Catalog search results |
---|---|
Return type: | list/Products.ZCatalog.Lazy.LazyMap |
Get a portal tool by name
Parameters: | name (string) – The name of the tool, e.g. portal_catalog |
---|---|
Returns: | Portal Tool |
Return type: | 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 |
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 |
Generate url information for the content object/catalog brain
Parameters: |
|
---|---|
Returns: | URL information mapping |
Return type: | dict |
Generate workflow information of the (first) assigned workflow
Parameters: |
|
---|---|
Returns: | Workflow information mapping |
Return type: | dict |
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 |
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 |
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 |
Generate API compatible data items for the given list of brains/objects
Parameters: |
|
---|---|
Returns: | A list of extracted data items |
Return type: | list |
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 |
paste items
update items
Update the content with the record data
Parameters: |
|
---|---|
Returns: | The updated content object |
Return type: | object |