Quickstart

This section gives a good introduction about plone.jsonapi.routes. It assumes you already have Plone and plone.jsonapi.routes installed. Since all the coming examples are executed directly in Google Chrome, it assumes that you have also installed JSONView and the Advanced Rest Client Application (see Installation for details)

Environment

The Plone site is hosted on http://localhost:8080/Plone. The JSON API is therefore located at http://localhost:8080/Plone/@@API/plone/api/1.0. Make sure your Plone site is located on the same URL, so you can directly click on the links within the exapmles.

Version

The version route prints out the current version of plone.jsonapi.routes.

http://localhost:8080/Plone/@@API/plone/api/1.0/version

{
    url: "http://localhost:8080/Plone/@@API/plone/api/1.0/version",
    date: "2017-05-12",
    version: "0.9.2",
    _runtime: 0.0001528865814208984
}

Note

The runtime indicates the time spent in milliseconds until the response is prepared.

Content Routes

These Resources are automatically generated for all available content types in Plone.

Each content route is located at the Base URL, e.g.

The name of each of these content routes is transformed to lower case, so it is also perfectly ok to call these Resources like so:

Calling a content route like this will return a JSON format similar to this:

{
    count: 14,
    pagesize: 25,
    items: [
        {},
        {},
        {},
        {},
        ...
    ],
    page: 1,
    _runtime: 0.0038590431213378906,
    next: null,
    pages: 1,
    previous: null
}

The Response Format in plone.jsonapi.routes content URLs is always the same. The top level keys (data after the first {) are meta informations about the gathered data.

The items list will contain the list of catalog results for the portal type requested. This means that each result contains just the metadata available in the catalog. Therfore, no object is “waked up” to retrieve the data at this stage. This is because of the APIs two step concept, which postpones expensive opreations, until the user really wants it.

All items are batched to increase performance of the API. The count number returns the total number objects found, while the page number returns the number of pages in the batch, which can be navigated with the next and previous links.

New in version 0.3: The result is now always batched. This means you get the items split up into batches onto multiple sites.

Getting the Full Data

To get all data from an object, you can either add the complete=True parameter, or you can request the data with the object UID.

The requested content(s) is now loaded by the API and all fields were gathered.

Note

Please keep in mind that large data sets with the ?complete=True Parameter might increase the loading time significantly.

Special Case: Files and Images

New in version 0.2: The object data contains now the base64 encoded file with the size and mimetype information.

New in version 0.7: You can pass in a filename in the JSON body to set the name of the file created. If omitted, the id or title will be used.

New in version 0.8: You can pass in a mimetype key to manually set the content type of the file. If omitted, the content type will be guessed by the filename. Default: application/octet-stream

New in version 0.8: The response data contains now the filename and the download url.

To create a new file in the portal, you have to HTTP POST to the create route:

http://localhost:8080/Plone/@@API/plone/api/1.0/file/create

The HTTP POST payload can look like this:

{
    "title": "Test.docx",
    "description": "A Word File",
    "filename": "test.docx",
    "parent_path": "/Plone/folder",
    "file":"UEsDBBQABgAIAAA..."
}

The file key in the HTTP POST payload contains the base64 encoded content of the file/image.

UID Route

To fetch the full data of an object immediately, it is also possible to append the UID of the object directly on the root URL of the API, e.g.:

Note

The given UID might seem different on your machine.

The response will give the data in the root of the JSON data, e.g.:

{
    "uid": "553ce5b2c55847a08dea2a7016a0e11a",
    "contributors": [],
    "file": "http://localhost:8080/Plone/w7614.pdf/@@download/file/w7614.pdf",
    "_runtime": 0.010680913925170898,
    "exclude_from_nav": false,
    "id": "w7614.pdf",
    "api_url": "http://localhost:8080/Plone/@@API/plone/api/1.0/file/553ce5b2c55847a08dea2a7016a0e11a",
    "title": "w7614.pdf",
    "parent_id": "Plone",
    "subjects": null,
    "author": "admin",
    "parent_url": "http://localhost:8080/Plone/@@API/plone/api/1.0/plonesite/0",
    "description": "",
    "tags": [],
    "portal_type": "File",
    "expires": null,
    "relatedItems": [],
    "parent_uid": "0",
    "effective": null,
    "language": "",
    "rights": "",
    "url": "http://localhost:8080/Plone/w7614.pdf",
    "created": "2017-05-12T12:47:38+02:00",
    "modified": "2017-05-12T12:47:38+02:00",
    "allow_discussion": null,
    "creators": [
        "admin"
    ]
}