Personium API Reference

Welcome to the Personium API Reference. This reference describes technical detailed specifications related to all of the APIs provided by Personium. Please refer to Request URL variable list for the variable of the request URL in this reference.

Unit Level API

The Unit Level API's belong to the unit that hosts a group of cells and provide functions such as creating cells or managing a group of created cells. In principle, Unit Level API's cannot be accessed using the access tokens issued by normal cells and can only be accessed with Unit User Tokens.

Unit Root URL

https://{UnitFQDN}/

Unit Control Objects

Most of the Unit Level API's are implemented in the form of Unit Control Objects. Since they conform with the OData standard, their manipulation can be made in a RESTful and standardized manner.

Cell Operations
Basic Operations Create     Retrieve List     Retrieve     Update     Delete

Other API's

Cell Level API

Cell Level API's are deployed under the following root URL.

Cell Root URL

{CellURL}

Cell Level API's provides the following features:

Most of these functions are implemented in the form of Cell Control Objects that can be operated with the OData protocol, which is a standard for performing relational data manipulation based on REST.

User and application Authentication

Authentication

Account (Cell Control Object)

Account Operations
Basic Operations Create     Retrieve     Retrieve List     Update     Partial Update     Delete
    Linking with other objects Link     Unlink     List Links
There is no link update. If you want to update, delete it and recreate it.
    Bound Object Manipulation Create     Retrieve List

Access control

Personium Cells employ Role-Based Access Control. A role can be defined in the form of Cell Control Object "Role". Cell-level ACL can be configured with the following API, where multiple pairs of role and granted privileges can be defined.

Configured ACL can be retrieved together with other properties, by sending regular WebDAV PROPFIND request to the root URL of the Cell.

Cell Control Object

Role Operations
Basic Operations Create     Retrieve     Retrieve List     Update     Partial Update     Delete
    Linking with other objects Link     Unlink     List Links
There is no link update. If you want to update, delete it and recreate it.
    Bound Object Manipulation Create     Retrieve List

Networking Cells

External Cell (Cell Control Object)

ExtCell Operations
Basic Operations Create     Retrieve     Retrieve List     Update     Partial Update     Delete
    Linking with other objects Link     Unlink     List Links
There is no link update. If you want to update, delete it and recreate it.
    Bound Object Manipulation Create     Retrieve List

Relation (Cell Control Object)

Relation Operations
Basic Operations Create     Retrieve     Retrieve List     Update     Partial Update     Delete
    Linking with other objects Link     Unlink     List Links
There is no link update. If you want to update, delete it and recreate it.
    Bound Object Manipulation Create     Retrieve List

ExtRole (Cell Control Object)

ExtRole Operations
Basic Operations Create     Retrieve     Retrieve List     Update     Partial Update     Delete
    Linking with other objects Link     Unlink     List Links
There is no link update. If you want to update, delete it and recreate it.
    Bound Object Manipulation Create     Retrieve List

Box creation and management inside the Cell

Box (Cell Control Object)

Box Operations
Basic Operations Create     Retrieve     Retrieve List     Update     Partial Update     Delete
    Linking with other objects Link     Unlink     List Links
There is no link update. If you want to update, delete it and recreate it.
    Bound Object Manipulation Create     Retrieve List

Message Exchange between Cells

Message Manipulation

Cell Control Object Operations
Sent Message Retrieve     Retrieve List     Delete
Received Message Retrieve     Retrieve List     Delete

Event processing

Event Processing Rule (Cell Control Object)

Rule Operations
Basic Operations Create     Retrieve     Retrieve List     Update     Delete
    Linking with other objects Link     Unlink     List Links    
There is no link update. If you want to update, delete it and recreate it.
    Bound Object Manipulation Create     Retrieve List

Event Log

Other functions

Cell root access

Exporting / Importing the contents inside the Cell

Snapshot file of Cell is created by export execution.
Import imports the contents of the snapshot file into Cell.
Snapshot file can be operated with WebDAV interface.

Operations
Export Execute     Retrieve progress
Import Execute     Retrieve progress
Snapshot Create/Update     Retrieve     Retrieve Properties     Delete

Box Level API

The Box Level API is a group of API's that reside on the following Box Root URL and serve for applications and others to manipulate their data.

Box Root URL

{CellURL}{BoxName}/

Box Level API's are based on an idea of WebDAV file system. Like ordinary file systems, it is possible to arrange / retrieve files, create / manage folders (collection), get list of files and folders, set / refer to access control, etc.

Also, because it supports the following special collections, it can handle not only file-like data but also various forms of data.
These special collections can be created in any path on the WebDAV space provided by Box.

Special collection Use Notes
OData Service Collection Relational data
Engine Service Collection Run customized logic
CALDAV Collection Calendar data Unimplemented
Link Collection Aliases to specific areas of other cells or other Box Unimplemented

Basic WebDAV Operations

Target Operations
Collection Create     Retrieve Settings     Change Settings     Move/Rename     Delete
File Create/Update     Retrieve     Retrieve Settings     Change Settings     Delete
Common Configure Access Control

* ACL setting (access control setting) is possible for all files and collections (including special collections).
* ACL setting can be acquired with the PROPFIND method.

OData Service Collection

Schema Definition

Create Retrieve Update Delete Other
EntityType Create Retrieve
Retrieve List
Update Delete
_$links Create List Update Delete
_via NavProp List
Property Create Retrieve
Retrieve List
Update Delete
_$links Create List Update Delete
AssociationEnd Create Retrieve
Retrieve List
Update Delete
_$links Create List Links Delete
_via NavProp List
ComplexType Create Retrieve
Retrieve List
Update Delete
_$links Create List Update Delete
ComplexTypeProperty Create Retrieve
Retrieve List
Update Delete
_$links Create List Update Delete
Service Document Retrieve/Schema Retrieve
Retrieve
Service Document Retrieve
Schema Retrieve

Data Manipulation

User-defined Entity Set Operations
Basic Operations Create     Retrieve     Retrieve List     Update     Partial Update     Delete
    Linking with other objects Link     Unlink     List Links    
There is no link update. If you want to update, delete it and recreate it.
    Bound Object Manipulation Create     Retrieve List

Engine Service Collection

You can register Personium application and server side logic created by Cell user and run it.
First, register the user logic as a file, set the service collection and associate with the path, so that
You can run the user logic for requests from any path under the collection.

Create Retrieve Update Delete Other
Service Collection Source Create Retrieve Apply Settings Delete Execute Service

Stream Collection

A collection that allows you to send and receive messages. By setting the queue and topic used for sending and receiving message queues, It is possible to send and receive for the set queue and send for the topic. Reception of topic is possible by WebSocket connection.

Operation Send/Receive
Stream Collection Change settings     OPTIONS Send     Receive     WebSocket connection

Common Information

OData Acquisition Common Queries

Query Single Acquisition List Acquisition
$format Query Yes Yes
$expand Query Yes Yes
$select Query Yes Yes
$orderby Query No Yes
$top Query No Yes
$skip Query No Yes
$filter Query No Yes
$inlinecount No Yes
Full-text Search (q) Query No Yes

Error Messages

Restrictions on Personium HTTP Implementation

CORS Support

Retrieve Cross Domain Policy File