plone.jsonapi.routes

Plone JSON API -- Routes

These details have not been verified by PyPI

Project links

Homepage

Project description

plone.jsonapi.routes

Author:: Ramon Bartl
Version:: 0.1

Introduction

This is an add-on package for plone.jsonapi.core which provides some basic URLs for Plone standard contents (and more).

Motivation

The routes package is built on top of the plone.jsonapi.core package to allow Plone developers to build modern (JavaScript) web UIs which communicate through a RESTful API with their Plone site.

Compatibility

The plone.jsonapi.routes should work with Plone 3 and 4.

Installation

The official release is on pypi, so you have to simply include plone.jsonapi.routes to your buildout config.

Example:

[buildout]

...

[instance]
...
eggs =
    ...
    plone.jsonapi.core
    plone.jsonapi.routes

After installation, the Plone API routes are available below the plone.jsonapi.core root URL (@@API) with the base /plone/api/1.0, for example http://localhost:8080/Plone/@@API/plone/api/1.0/api.json.

There is also an overview of the registered routes which can be accessed here:

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

API Routes

BASE_URL:: /plone/api/1.0

This is an overview of the provided API Routes. The basic content routes provide all an interface for CRUD operations.

CRUD URL Scheme:

OPERATION	URL	METHOD	PAYLOAD
VIEW	<BASE_URL>/<RESOURCE>/<uid:optional>	GET	–
CREATE	<BASE_URL>/<RESOURCE>/create/<uid:optional>	POST	JSON
UPDATE	<BASE_URL>/<RESOURCE>/update/<uid:optional>	POST	JSON
DELETE	<BASE_URL>/<RESOURCE>/delete/<uid:optional>	POST	JSON

Response Format

The response format is for all resources the same.

Example:

{
    url: "http://localhost:8080/Plone/@@API/plone/api/1.0/documents",
    count: 0,
    _runtime: 0.0021538734436035156,
    items: [ ]
}

url: The resource root url
count: Count of found results
_runtime: The processing time in milliseconds after the request was received until the respone was prepared.
items: An array of result items

Content URLs

BASE_URL:: /plone/api/1.0
SCHEME:: BASE_URL/RESOURCE

All content informations are dynamically gathered by the contents schema definition through the IInfo adapter. It is possible to define a more specific adapter for your content type to control the data returned by the API.

Folders

RESOURCE:: folders

API Resource for Folders

VIEW	<BASE_URL>/folders/	GET
CREATE	<BASE_URL>/folders/create	POST
UPDATE	<BASE_URL>/folders/update	POST
DELETE	<BASE_URL>/folders/delete	POST

Documents

RESOURCE:: documents

API Resource for Documents

VIEW	<BASE_URL>/documents/	GET
CREATE	<BASE_URL>/documents/create	POST
UPDATE	<BASE_URL>/documents/update	POST
DELETE	<BASE_URL>/documents/delete	POST

Events

RESOURCE:: events

API Resource for Events

VIEW	<BASE_URL>/events/	GET
CREATE	<BASE_URL>/events/create	POST
UPDATE	<BASE_URL>/events/update	POST
DELETE	<BASE_URL>/events/delete	POST

Files

RESOURCE:: files

API Resource for Files

VIEW	<BASE_URL>/files/	GET
CREATE	<BASE_URL>/files/create	POST
UPDATE	<BASE_URL>/files/update	POST
DELETE	<BASE_URL>/files/delete	POST

Images

RESOURCE:: images

API Resource for Images

VIEW	<BASE_URL>/images/	GET
CREATE	<BASE_URL>/images/create	POST
UPDATE	<BASE_URL>/images/update	POST
DELETE	<BASE_URL>/images/delete	POST

Links

RESOURCE:: links

API Resource for Links

VIEW	<BASE_URL>/links/	GET
CREATE	<BASE_URL>/links/create	POST
UPDATE	<BASE_URL>/links/update	POST
DELETE	<BASE_URL>/links/delete	POST

News Items

RESOURCE:: newsitems

API Resource for News Items

VIEW	<BASE_URL>/newsitems/	GET
CREATE	<BASE_URL>/newsitems/create	POST
UPDATE	<BASE_URL>/newsitems/update	POST
DELETE	<BASE_URL>/newsitems/delete	POST

Topics

RESOURCE:: topics

API Resource for Topics

VIEW	<BASE_URL>/topics/	GET
CREATE	<BASE_URL>/topics/create	POST
UPDATE	<BASE_URL>/topics/update	POST
DELETE	<BASE_URL>/topics/delete	POST

Collections

RESOURCE:: collections

API Resource for Collections

VIEW	<BASE_URL>/collections/	GET
CREATE	<BASE_URL>/collections/create	POST
UPDATE	<BASE_URL>/collections/update	POST
DELETE	<BASE_URL>/collections/delete	POST

Users

RESOURCE:: users

API Resource for Plone Users

VIEW	<BASE_URL>/users	GET
GET CURRENT	<BASE_URL>/users/current	GET

Examples

These examples show the basic usage of the API. All examples are done from the command line using curl.

Imagine an empty Plone site with just 2 Folders:

Folder 1

Folder 2

Now lets list these folder. Therefore we use the documents resource of the API:

curl -XGET http://localhost:8080/Plone/@@API/plone/api/1.0/folders | python -mjson.tool

{
    "_runtime": 0.0024950504302978516,
    "count": 2,
    "items": [
        {
            "api_url": "http://localhost:8080/Plone/@@API/plone/api/1.0/folders/1b3e6ccde22b48778d5af5768ee49983",
            "created": "2014-01-23T10:10:53+01:00",
            "description": "The first Folder",
            "effective": "2014-01-23T10:11:15+01:00",
            "id": "folder-1",
            "modified": "2014-01-23T10:11:15+01:00",
            "portal_type": "Folder",
            "tags": [],
            "title": "Folder 1",
            "type": "Folder",
            "uid": "1b3e6ccde22b48778d5af5768ee49983",
            "url": "http://localhost:8080/Plone/folder-1"
        },
        {
            "api_url": "http://localhost:8080/Plone/@@API/plone/api/1.0/folders/0198f943bd2b48a8970b04d637f74888",
            "created": "2014-01-23T10:11:05+01:00",
            "description": "The second Folder",
            "effective": "2014-01-23T10:11:15+01:00",
            "id": "folder-2",
            "modified": "2014-01-23T10:11:15+01:00",
            "portal_type": "Folder",
            "tags": [],
            "title": "Folder 2",
            "type": "Folder",
            "uid": "0198f943bd2b48a8970b04d637f74888",
            "url": "http://localhost:8080/Plone/folder-2"
        }
    ],
    "url": "http://localhost:8080/Plone/@@API/plone/api/1.0/folders"
}

As you can see, the two folders get listed. Also note, that for reasons of performance, the request to a root URL of a resource contains only the catalog results. The objects don’t get waked up until we request a specific item.

Now we will request a specific folder, which will wake up the object to show more detailed informations:

curl -XGET http://localhost:8080/Plone/@@API/plone/api/1.0/folders/1b3e6ccde22b48778d5af5768ee49983 | python -mjson.tool

{
    "_runtime": 0.008948087692260742,
    "count": 1,
    "items": [
        {
            "allowDiscussion": false,
            "api_url": "http://localhost:8080/Plone/@@API/plone/api/1.0/folders/1b3e6ccde22b48778d5af5768ee49983",
            "constrainTypesMode": 0,
            "contributors": [],
            "created": "2014-01-23T10:10:53+01:00",
            "creation_date": "2014-01-23T10:10:53+01:00",
            "creators": [
                "admin"
            ],
            "description": "The first Folder",
            "effective": "2014-01-23T10:11:15+01:00",
            "effectiveDate": "2014-01-23T10:11:15+01:00",
            "excludeFromNav": false,
            "expirationDate": null,
            "id": "folder-1",
            "immediatelyAddableTypes": [],
            "language": "de",
            "locallyAllowedTypes": [],
            "location": "",
            "modification_date": "2014-01-23T10:11:15+01:00",
            "modified": "2014-01-23T10:11:15+01:00",
            "nextPreviousEnabled": false,
            "parent_id": "Plone",
            "parent_uid": 0,
            "portal_type": "Folder",
            "relatedItems": [],
            "rights": "",
            "subject": [],
            "tags": [],
            "title": "Folder 1",
            "type": "Folder",
            "uid": "1b3e6ccde22b48778d5af5768ee49983",
            "url": "http://localhost:8080/Plone/folder-1"
        }
    ],
    "url": "http://localhost:8080/Plone/@@API/plone/api/1.0/folders"
}

The response of a specific resource is much more detailed since we gather the schema fields of the object. Also note, that if the content is located below the Plone site root, the parent_uid will be 0.

Now lets create a document below this folder. Therefore, the request needs to be authenticated. I simply “steal” the __ac cookie value of my authenticated browser session:

curl -XPOST -H "Content-Type: application/json" -d '{"parent_uid":"1b3e6ccde22b48778d5af5768ee49983", "title":"A Document below Folder 1"}' http://localhost:8080/Plone/@@API/plone/api/1.0/documents/create  --cookie "__ac=NjE2NDZkNjk2ZTo2MTY0NmQ2OTZl" | python -mjson.tool

{
    "_runtime": 0.08417892456054688,
    "count": 1,
    "items": [
        {
            "allowDiscussion": false,
            "api_url": "http://localhost:8080/Plone/@@API/plone/api/1.0/documents/c1b61148a3a3489c9ae5f18a8b552ceb",
            "contributors": [],
            "creation_date": "2014-01-23T11:54:02+01:00",
            "creators": [
                "admin"
            ],
            "description": "",
            "effectiveDate": null,
            "excludeFromNav": false,
            "expirationDate": null,
            "id": "a-document-below-folder-1",
            "language": "de",
            "location": "",
            "modification_date": "2014-01-23T11:54:02+01:00",
            "parent_id": "folder-1",
            "parent_uid": "1b3e6ccde22b48778d5af5768ee49983",
            "parent_url": "http://localhost:8080/Plone/@@API/plone/api/1.0/folders/1b3e6ccde22b48778d5af5768ee49983",
            "presentation": false,
            "relatedItems": [],
            "rights": "",
            "subject": [],
            "tableContents": false,
            "text": "",
            "title": "A Document below Folder 1"
        }
    ],
    "url": "http://localhost:8080/Plone/@@API/plone/api/1.0/documents/create"
}

Note how the parent_uid is updated to the one of Folder 1 and the generated api_url points to the correct folders resource here.

Now lets update this document. Therefore we post a new JSON object with the informations to the documents api url:

curl -XPOST -H "Content-Type: application/json" -d '{"uid": "c1b61148a3a3489c9ae5f18a8b552ceb", "description":"The description changed", "text": "Some Text"}' http://localhost:8080/Plone/@@API/plone/api/1.0/documents/update  --cookie "__ac=NjE2NDZkNjk2ZTo2MTY0NmQ2OTZl" | python -mjson.tool

{
    "_runtime": 0.049546003341674805,
    "count": 1,
    "items": [
        {
            "allowDiscussion": false,
            "api_url": "http://localhost:8080/Plone/@@API/plone/api/1.0/documents/c1b61148a3a3489c9ae5f18a8b552ceb",
            "contributors": [],
            "creation_date": "2014-01-23T11:54:02+01:00",
            "creators": [
                "admin"
            ],
            "description": "The description changed",
            "effectiveDate": null,
            "excludeFromNav": false,
            "expirationDate": null,
            "id": "a-document-below-folder-1",
            "language": "de",
            "location": "",
            "modification_date": "2014-01-23T12:11:33+01:00",
            "parent_id": "folder-1",
            "parent_uid": "1b3e6ccde22b48778d5af5768ee49983",
            "parent_url": "http://localhost:8080/Plone/@@API/plone/api/1.0/folders/1b3e6ccde22b48778d5af5768ee49983",
            "presentation": false,
            "relatedItems": [],
            "rights": "",
            "subject": [],
            "tableContents": false,
            "text": "<p>Some Text</p>",
            "title": "A Document below Folder 1"
        }
    ],
    "url": "http://localhost:8080/Plone/@@API/plone/api/1.0/documents/update"
}

Note how the description and text changed!

Finally, lets delete the item:

curl -XPOST -H "Content-Type: application/json" -d '{"uid": "c1b61148a3a3489c9ae5f18a8b552ceb"}' http://localhost:8080/Plone/@@API/plone/api/1.0/documents/delete  --cookie "__ac=NjE2NDZkNjk2ZTo2MTY0NmQ2OTZl" | python -mjson.tool

{
    "_runtime": 0.0047149658203125,
    "count": 1,
    "items": [
        {
            "deleted": true,
            "id": "a-document-below-folder-1"
        }
    ],
    "url": "http://localhost:8080/Plone/@@API/plone/api/1.0/documents/delete"
}

The document is now gone:

curl -XGET http://localhost:8080/Plone/@@API/plone/api/1.0/documents | python -mjson.tool

{
    "_runtime": 0.0019440650939941406,
    "count": 0,
    "items": [],
    "url": "http://localhost:8080/Plone/@@API/plone/api/1.0/documents"
}

License

MIT - do what you want

Changelog

0.1 - 2014-01-23

first public release

Project details

These details have not been verified by PyPI

Project links

Homepage

Release history Release notifications | RSS feed

0.9.4

Oct 17, 2017

0.9.3

May 14, 2017

0.9.2

May 12, 2017

0.9.1

Apr 20, 2017

0.9.0

Jan 12, 2017

0.8.9

Jan 11, 2017

0.8.8

Jan 10, 2017

0.8.7

Jan 10, 2017

0.8.6

Apr 8, 2016

0.8.5

Apr 8, 2016

0.8.4

Jan 14, 2016

0.8.3

Sep 14, 2015

0.8.2

Sep 9, 2015

0.8.1

Sep 6, 2015

0.8

Jul 20, 2015

0.7

Jul 9, 2015

0.6

Feb 21, 2015

0.5

Feb 21, 2015

0.4

Jan 13, 2015

0.3

Oct 14, 2014

0.2

Mar 5, 2014

This version

0.1

Jan 23, 2014

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

plone.jsonapi.routes-0.1.tar.gz (21.2 kB view details)

Uploaded Jan 23, 2014 Source

File details

Details for the file plone.jsonapi.routes-0.1.tar.gz.

File metadata

Download URL: plone.jsonapi.routes-0.1.tar.gz
Upload date: Jan 23, 2014
Size: 21.2 kB
Tags: Source
Uploaded using Trusted Publishing? No

File hashes

Hashes for plone.jsonapi.routes-0.1.tar.gz
Algorithm	Hash digest
SHA256	`acd8c167e18361eb1e8faf63727b1eebea8bbbb89f36b91a5b42e844fd3960de`
MD5	`a6288c60075ea4374db250141205c521`
BLAKE2b-256	`5d133099346562935b14e5f06f3dd3c23f266b20094a7290e96115de8dc2e321`

See more details on using hashes here.

plone.jsonapi.routes 0.1

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

Folders

Documents

Events

Files

Images

Links

News Items

Topics

Collections

Users

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

File details

File metadata

File hashes