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

• Get Unit Metadata
• Cell Recursive Deletion

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:

• User and application Authentication
• Access control
• Networking Cells
• Box creation and management
• Message exchange between Cells
• Event processing
• Other 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

• OAuth2.0 Authorization Endpoint
• OAuth2.0 Token Endpoint
• Change Password
• OAuth2.0 Token Introspection
• Get Cell Certs

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.

• Cell-level ACL Configuralion

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

• Retrieve Properties
• Change Properties

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

• Export Box
• Install Box
• Retrieve Box Meta Data
• Retrieve URL
• Recursive Delete

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

• Send Message
• Change Status (Approve / Decline, etc.)

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

Event processing

• Events Overview
• Accept External Events
• Web Socket connection to Event Bus

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

• Retrieve List of Internal Rule information

Event Log

• Retrieve Log File
• List of Log Files
• Retrieve Log File Information
• Delete Log File

Other functions

Cell root access

• Retrieve Cell Root
• Retrieve Cell Metadata

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

Viewing Schema

	Operations
Schema Retrieval	ATOM Service Document     EDMX Schema

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

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

• Batch Operation

Engine Service Collection

Personium applications and Cell users can create server-side logics and run them on each Cell. It is enabled with a special collection called Engine Service Collection (ESC). Each ESC has its source directory where user logic can be registered as script files. After script files are registered in the directory and the routing from any paths under ESC to the registered script files can be configured, HTTP request to the configured path will be handled with the registered script.

	Operations
Script files	Create     Retrieve     Delete
Configure / Execute	Apply Settings     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