Overview

Architecture
Actor Overview
Technologies
Roadmap
History

Getting started

Prerequisites
Download
Hello World
Hello World with Kafka
Examples

Documentation

Actor Reference
API Reference
The event log
Handling and forwarding
State calculation
Scaling out
Command line parameters
Configuration Reference





























API reference


Top-level entities

Below you can find an overview of the complete API of Coral. The following set of “top-level entities” are present in Coral:

  • Platform
    Platform calls concern all platform and cluster-level interactions that deal with Coral as a whole and not the individual runtimes. You need to have special administrator privileges to change and look up platform settings.
  • Runtimes
    Runtime calls deal with individual runtimes on the platform. You need to have permission to access a specific runtime.
  • Actors
    Actor calls deal with individual actors within a certain runtime. You need to have permission to access the runtime in which the actor resides.
  • Users
    User calls deal with creating and removing users and looking up user information. You need to have special administrator privileges to add and remove users from the platform.
  • Permissions
    Permission calls deal with creating, removing and changing user permissions. You need to have special administrator privileges to create, remove and change user permissions.
  • Projects
    Project calls deal with creating, removing and changing project definitions. Currently, the project calls are not implemented yet but will be implemented in a future release.

### Referring to runtimes

In the Coral platform, there are three ways to refer to runtimes:

  • By name
    Access the runtime by name. If you do this, the platform implicitly assumes the current unique user name prefixed before the runtime name: /api/runtimes/runtime1 becomes /api/runtimes/neo-runtime1 if the current unique user name is “neo”. In the case of accept-all authentication, an implicit user with unique name “coral” is assumed.

           Example:

  • By owner and name
    Access the runtime by owner “dash” name. This is the internal unique name that Coral keeps to refer to runtimes.

           Example:

           This method is required if referring to a runtime of which the current user is not the            owner. In the case of accept-all authentication, “coral” is used as the user name, but it is not            necessary to explicitly state this.

  • By UUID
    This method refers to the runtime by its unique UUID assigned when creating the runtime. The user name should not be put before the UUID when referring to a runtime like this; the UUID is already unique across the entire platform.

           Example:

Referring to other entities

Permissions are always referred to by their UUID. Users can be referred to by their UUID or their unique user name. Actors are always referred to by their unique name in a runtime.

API

For each API call, the following information is provided:

  • The method (HTTP verb)
  • The endpoint
  • A description of the action
  • The JSON input format
  • An example of the JSON input format
  • The JSON result format
  • An example of the JSON result format
  • Possible error codes

Click on the link to go to the details of a specific call.

Platform

Show platform statistics, change platform settings and add and remove nodes from the cluster.

URL action
                                    POST /api/platform/cluster Join or remove a node from the cluster                
GET /api/platform/cluster Returns all machines in the Coral platform
GET /api/platform/cluster/<id> Get information on machine <id>
GET /api/platform/stats Show statistics for the entire platform
GET /api/platform/settings Returns all settings of the platform


Runtimes

Create, start and stop runtimes and get information and statistics of runtimes.

URL action
                                                POST /api/runtimes Create a new runtime                                                 
GET /api/runtimes/<id> Gets the definition of runtime <id>
GET /api/runtimes/<id>/actors Gets all actors for runtime <id>
GET /api/runtimes/<id>/links Gets all links for runtime <id>
GET /api/runtimes/<id>/stats Gets statistics about runtime <id>
PATCH /api/runtimes/<id> Starts or stops runtime <id>
DELETE /api/runtimes/<id> Deletes runtime <id>
DELETE /api/runtimes Delete all runtimes


Actors

Interact with individual actors in a runtime and get actor statistics.

URL action
POST /api/runtimes/<rid>/actors/<aid> Post JSON to actor <aid> in runtime <rid>
POST /api/runtimes/<rid>/actors/<aid>/shunt Post JSON to <aid> in <rid> and return
GET /api/runtimes/<id>/actors Gets information of all actors in runtime <id>
GET /api/runtimes/<rid>/actors/<aid>/stats Get stats about actor <aid> in runtime <rid>


Users

Add and remove users from the platform.

URL action
                                                          POST /api/users Post a new user with permissions                         
GET /api/users/<id> Returns information for user <id>
GET /api/users Returns all users on the platform
DELETE /api/users/<id> Deletes user <id>


Permissions

Add, remove and change permissions for users on the platform.

URL action
               POST /api/runtimes/<id>/permissions Add a new permission to runtime <id>
GET /api/runtimes/<id>/permissions Gets all permissions for runtime <id>
PATCH /api/runtimes/<id>/permissions Set permission granted/denied in runtime <id>
DELETE /api/runtimes/<id>/permissions Delete a permission from runtime <id>


Projects

Create, delete or change projects.

URL action
                                                    POST /api/projects Create a new project                                                  
GET /api/projects Get all projects on the platform
PATCH /api/projects/<id> Update a project definition of project <id>
DELETE /api/projects/<id> Delete project <id>