Calling RPC methods in C1 Core¶

A module can call any RPC method in C1 Core. This can be restricted by ACLs in C1 Core. Currently all modules are regarded as trusted though, so there are no ACL restrictions (there is an ACL in place that allows full access).

Selecting an endpoint¶

Please read the section about endpoint usage first. The seed servers for C1 Core are as follows:

Development¶

Host name	Port
n0r0c0.core-dev.sensaru.net	2000
n1r0c0.core-dev.sensaru.net	2000
n2r0c0.core-dev.sensaru.net	2000

Staging¶

Host name	Port
n0r0c0.core-staging.sensaru.net	3000
n1r0c0.core-staging.sensaru.net	3000
n2r0c0.core-staging.sensaru.net	3000

Production¶

Host name	Port
n0r0c0.core.sensaru.net	4000
n1r0c0.core.sensaru.net	4000
n2r0c0.core.sensaru.net	4000

Retrieving the list of endpoints from the seed servers¶

The list of endpoints can be retrieved by calling the RPC method getEndpoints on any server. This method has no paramters. The method returns an array with the host names of the available endpoints. Please note that the port is not returned as it is always the same. A result might look like this:

[
    n5r0c0.core.sensaru.net,
    n0r1c0.core.sensaru.net,
    n4r0c0.core.sensaru.net,
    n7r2c0.core.sensaru.net,
]

The seed servers can be part of this list, but this is not required and will not be the case if the load on the seed servers is high.

REST transactions¶

You can also execute REST requests by using RPC. We call this "REST transaction". Using this, multiple REST requests can be executed in one single RPC request. This

saves time
and enables C1 Core to rollback all changes when one of the requests failed.

The HTTP path for REST transactions is /api/v1/rpc. HTTP POST must be used. A simple REST transaction might look like this:

[
    {"method": "REST/GET user", "params": {}},
    {"method": "REST/GET business_partners", "params": {}}
]

As you can see, this follows the JSON-RPC specification for multiple RPC calls with one request. The RPC calls are wrapped in an array.

Method name¶

The method name for a REST transaction always starts with REST/ followed by the HTTP method (e. g. GET). After a space character the REST path is appended without /api/v1/.

REST/<HTTP method><space character><REST path without /api/v1/>

Using results from previous method calls¶

It is common, that you require data for a method call that is returned from a previous one. You can access this data using the Mustache template engine. Any array index or property name can be accessed in any level. Let's assume this is our REST transaction:

[
    {"method": "REST/GET user", "params": {}},
    .
    .
    .
]

After REST/GET user is executed, our result array looks like this:

[
    {"result": {..., "systemProvider": "48109350-1db6-11e9-8e66-2f71a0be4cc5", ...}, ...}
]

To get the system provider in the next method call, we can use the Mustache template {{{0.result.systemProvider}}} as 0 is the index in the outer array, result is the property name in the next level object and systemProvider is the property name of the inner object. {{{0.result.systemProvider}}} is replaced with 48109350-1db6-11e9-8e66-2f71a0be4cc5.

So a full REST transaction to get information about the system provider of the currently logged in user might look like this:

[
    {"method": "REST/GET user", "params": {}},
    {"method": "REST/GET system_providers/{{{0.result.systemProvider}}}", "params": {}}
]

REST requests that require additional headers¶

Some REST requests require the principal to be set in custom HTTP headers. In REST transactions this cannot be done. To set the principal - when required - in a REST transaction, use the properties sp for the system provider ID, sd for the system distributor ID and bp for the business partner ID. For example:

[
    {
        "method": "REST/POST ...",
        "params": {},
        "sp": "48109350-1db6-11e9-8e66-2f71a0be4cc5",
        "sd": "65490af0-ef62-11e9-847a-a58a2ea33526",
        "bp": "0604b020-7905-11eb-ad7b-f9e2c6c59018"
    },
    .
    .
    .
]

Of course Mustache templates can be used here as well.