APIs

Gateway server APIs are the main request endpoints for Rierino platform, when deployed in full.

Request APIs

Request APIs provide ability to communicate with micro-services, where an executor responsible for the given channel sends the request and returns response to the caller.

The method of request (e.g. GET vs POST) is used only by some executors (e.g. CRUDExecutor), whereas the others treat all methods the same (e.g. KafkaExecutor).

For all requests, certain details can be provided through headers or cookies:

• Origin: Identifies the source of a request (such as application, user geolocation), and can be populated using:

  • "Rierino-Origin" Header: As base64 encoded Json string

  • "Rierino-Origin" Cookie: As base64 encoded Json string

  • "User-Agent" Header: Sets origin.agent

  • "Referrer" Header: Sets origin.referrer

  • "X-Forwarded-For", "Forwarded" Headers, Request Address: Sets origin.ip

• Auth: Provides authentication details (such as credentials, api key or tokens), and can be populated using:

  • "Rierino-Auth.[parameter]" Header: Sets auth.parameter

  • "Rierino-Auth.[parameter]" Cookie: Sets auth.parameter

  • "Bearer" Authorization Header: As base64 encoded Json string prefixed with "base64="

  • "Bearer" Authorization Header: As comma separated "parameter:value,parameter:value" pairs prefixed with "multi="

  • "Basic" Authorization Header: As base64 encoded username:password parameters

  • "[parameter]" Authorization Header: Sets auth.parameter where comma separated "parameter value, parameter value" pairs are allowed

Request with URL parameters for payload

Basic request passed on to the [channel] executor, on [path], where URL parameters are used to populate payload.

get

/api/request/{channel}//{path}

Path parameters

channelstringrequired

Gateway channel for execution

Example: crud

pathstringrequired

Path for calling specific action / saga on gateway channel

Example: product

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'localhost:1234/api/request/{channel}/{path}'

200

401

403

500

501

200

No body

OK

Request with "data" URL parameter as contents

Full body request where [data] URL parameter can contain all details, including origin, auth and payload as a Json string.

get

/api/request/full/{channel}//{path}

Path parameters

channelstringrequired

Gateway channel for execution

Example: crud

pathstringrequired

Path for calling specific action / saga on gateway channel

Example: product

Query parameters

datastring

Json string representation of a request

Example: {origin:{}, auth:{}, payload:{}}

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'localhost:1234/api/request/full/{channel}/{path}'

200

401

403

500

501

200

No body

OK

Request with "data" URL parameter as base64 contents

Full body request where [data] URL parameter can contain all details, including origin, auth and payload as a base64 encoded Json string.

get

/api/request/full/e/{channel}//{path}

Path parameters

channelstringrequired

Gateway channel for execution

Example: crud

pathstringrequired

Path for calling specific action / saga on gateway channel

Example: product

Query parameters

datastring

Base64 encoded Json string representation of a request

Example: e29yaWdpbjp7fSwgYXV0aDp7fSwgcGF5bG9hZDp7fX0=

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'localhost:1234/api/request/full/e/{channel}/{path}'

200

401

403

500

501

200

No body

OK

Request with body for payload

Basic request passed on to the [channel] executor, on [path], where body is used to populate payload.

post

/api/request/{channel}//{path}

Path parameters

channelstringrequired

Gateway channel for execution

Example: crud

pathstringrequired

Path for calling specific action / saga on gateway channel

Example: product

Body

object

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/request/{channel}/{path}' \
  --header 'Content-Type: application/json'

200

401

403

500

501

200

No body

OK

Request with body for full details

Basic request passed on to the [channel] executor, on [path], where body provides full details, including origin, auth and payload.

post

/api/request/full/{channel}//{path}

Path parameters

channelstringrequired

Gateway channel for execution

Example: crud

pathstringrequired

Path for calling specific action / saga on gateway channel

Example: product

Body

originobject

authobject

payloadobject

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/request/full/{channel}/{path}' \
  --header 'Content-Type: application/json' \
  --data '{"origin":{},"auth":{},"payload":{}}'

200

401

403

500

501

200

No body

OK

Request with body for base64 encoded details

Basic request passed on to the [channel] executor, on [path], where body is a base64 string encoded Json, which provides full details, including origin, auth and payload.

post

/api/request/full/e/{channel}//{path}

Path parameters

channelstringrequired

Gateway channel for execution

Example: crud

pathstringrequired

Path for calling specific action / saga on gateway channel

Example: product

Body

string

Base64 encoding of Json body with origin, auth and payload

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/request/full/e/{channel}/{path}' \
  --header 'Content-Type: application/json'

200

401

403

500

501

200

No body

OK

Request with body for payload

Basic request passed on to the [channel] executor, on [path], where body is used to populate payload.

put

/api/request/{channel}//{path}

Path parameters

channelstringrequired

Gateway channel for execution

Example: crud

pathstringrequired

Path for calling specific action / saga on gateway channel

Example: product

Body

object

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'localhost:1234/api/request/{channel}/{path}' \
  --header 'Content-Type: application/json'

200

401

403

500

501

200

No body

OK

Request with body for payload

Basic request passed on to the [channel] executor, on [path], where body is used to populate payload.

patch

/api/request/{channel}//{path}

Path parameters

channelstringrequired

Gateway channel for execution

Example: crud

pathstringrequired

Path for calling specific action / saga on gateway channel

Example: product

Body

object

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PATCH \
  --url 'localhost:1234/api/request/{channel}/{path}' \
  --header 'Content-Type: application/json'

200

401

403

500

501

200

No body

OK

Request with URL parameters for payload

Basic request passed on to the [channel] executor, on [path], where URL parameters are used to populate payload.

delete

/api/request/{channel}//{path}

Path parameters

channelstringrequired

Gateway channel for execution

Example: crud

pathstringrequired

Path for calling specific action / saga on gateway channel

Example: product

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'localhost:1234/api/request/{channel}/{path}'

200

401

403

500

501

200

No body

OK

Auth APIs

Auth APIs coordinate authentication flows with authentication servers across different gateway channels.

New user registration

Receives a registration payload as body, which can include user details (such as name, surname). If [thru] is true, registers a new user with the authentication server. Otherwise resolves provided access token to register an existing user record with the back-end services. In both scenarios, register endpoint is called on [type] execution channel.

post

/api/auth/register/{channel}//{type}

Path parameters

channelstringrequired

Gateway channel for authentication

Example: crud

typestringrequired

Type of authentication to use

Example: customer

Query parameters

thrustring

Whether request should be passed on to authentication servers too

Example: true

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/auth/register/{channel}/{type}'

200

401

403

500

501

200

No body

OK

Existing user login

Logs a user into the system, returning gateway tokens. If [thru] is true, logs in the user with the authentication server first. Otherwise resolves provided access token to login an existing user record with the back-end services. In both scenarios, login endpoint is called on [type] execution channel. If [cookie] is true, tokens are returned as cookie values. If [remember] is true, refresh token expire in longer duration.

post

/api/auth/login/{channel}//{type}

Path parameters

channelstringrequired

Gateway channel for authentication

Example: crud

typestringrequired

Type of authentication to use

Example: customer

Query parameters

thrustring

Whether request should be passed on to authentication servers too

Example: true

cookiestring

Whether tokens should be returned in cookies

Example: true

rememberstring

Whether tokens should have longer expirations

Example: true

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/auth/login/{channel}/{type}'

200

401

403

500

501

200

No body

OK

User tokens refresh

Refreshes gateway tokens using refresh tokens, also calling refresh endpoint on [type] execution channel. If [cookie] is true, tokens are returned as cookie values.

post

/api/auth/refresh/{channel}//{type}

Path parameters

channelstringrequired

Gateway channel for authentication

Example: crud

typestringrequired

Type of authentication to use

Example: customer

Query parameters

cookiestring

Whether tokens should be returned in cookies

Example: true

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/auth/refresh/{channel}/{type}'

200

401

403

500

501

200

No body

OK

Existing user logout

Logs out users from the system, clearing gateway tokens. If [thru] is true, logs out the user from the authentication server as well. If [cookie] is true, cleared tokens are returned as cookie values.

post

/api/auth/logout/{channel}//{type}

Path parameters

channelstringrequired

Gateway channel for authentication

Example: crud

typestringrequired

Type of authentication to use

Example: customer

Query parameters

thrustring

Whether request should be passed on to authentication servers too

Example: true

cookiestring

Whether tokens should be returned in cookies

Example: true

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/auth/logout/{channel}/{type}'

200

401

403

500

501

200

No body

OK

Existing user removal

Deletes a user from the system. If [thru] is true, deletes the user from the authentication server as well. In both scenarios, delete endpoint is called on [type] execution channel. If [cookie] is true, cleared tokens are returned as cookie values.

post

/api/auth/delete/{channel}//{type}

Path parameters

channelstringrequired

Gateway channel for authentication

Example: crud

typestringrequired

Type of authentication to use

Example: customer

Query parameters

thrustring

Whether request should be passed on to authentication servers too

Example: true

cookiestring

Whether tokens should be returned in cookies

Example: true

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/auth/delete/{channel}/{type}'

200

401

403

500

501

200

No body

OK

Tracker APIs

Tracker APIs provide ability to post front-end traffic data, in case back-end tracking is not possible for a specific use case. Example uses include front-end or CDN caching of API responses, front-end events that do not require API calls (such as widget interactions) or Rierino platform integration with other back-end modules that do not provide tracking capabilities.

New tracking event

Posts an event to tracking service and topic, as if it is the response from an API call on [channel] and [path], where request body represents the event payload. Received data is subject to same checks and transformations of a gateway request, meaning it will be authenticated, sessionized and its headers and cookies will be used to enrich request metadata.

post

/api/track/{channel}//{path}

Path parameters

channelstringrequired

Gateway channel as origin of event

Example: crud

pathstringrequired

Path for registering specific action / saga on gateway channel

Example: product

Body

object

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/track/{channel}/{path}' \
  --header 'Content-Type: application/json'

200

401

403

500

501

200

No body

OK

File APIs

File APIs provide ability to interact with file system services, listing, uploading and deleting files, typically used for export/import operations. For all APIs, user authentication is done using headers and cookies similar to other gateway APIs. All APIs also have a api/file/sudo/* version, which allows root level access to a file system for admin users.

Get list of files

Returns list of files in [service] file system under path assigned to current user id or "anonymous".

get

/api/file/{service}

Path parameters

servicestringrequired

File system to use for operations

Example: default_hdfs

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'localhost:1234/api/file/{service}'

200

401

403

500

501

200

No body

OK

Downloads a selected file

Downloads file from [filePath] in [service] file system under path assigned to current user id or "anonymous", as application/octet-stream.

get

/api/file/{service}//{filePath}

Path parameters

servicestringrequired

File system to use for operations

Example: default_hdfs

filePathstringrequired

Relative path to selected file

Example: test/sample.json

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'localhost:1234/api/file/{service}/{filePath}'

200

401

403

500

501

200

No body

OK

Upload unnamed file

Uploads a new file with globally unique name in [service] file system under path assigned to current user id or "anonymous".

post

/api/file/{service}

Path parameters

servicestringrequired

File system to use for operations

Example: default_hdfs

Body

string · binary

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/file/{service}' \
  --header 'Content-Type: application/octet-stream'

200

401

403

500

501

200

No body

OK

Upload named file

Uploads a new file with on [filePath] in [service] file system under path assigned to current user id or "anonymous".

post

/api/file/{service}//{filePath}

Path parameters

servicestringrequired

File system to use for operations

Example: default_hdfs

filePathstringrequired

Relative path to selected file

Example: test/sample.json

Body

string · binary

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/file/{service}/{filePath}' \
  --header 'Content-Type: application/octet-stream'

200

401

403

500

501

200

No body

OK

Deletes a selected file

Deletes file from [filePath] in [service] file system under path assigned to current user id or "anonymous".

delete

/api/file/{service}//{filePath}

Path parameters

servicestringrequired

File system to use for operations

Example: default_hdfs

filePathstringrequired

Relative path to selected file

Example: test/sample.json

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request DELETE \
  --url 'localhost:1234/api/file/{service}/{filePath}'

200

401

403

500

501

200

No body

OK

Control APIs

Control APIs provide ability to query and refresh gateway components (system, channel, service, token) in real-time.

Show gateway component configuration

Issues SHOW command for [component] and [id], returning its current settings. If [id] is *, all component values are listed for the [component].

get

/api/control/{component}//{id}

Path parameters

componentanyrequired

Gateway component type to apply command on

Example: system

idanyrequired

Gateway component id to apply command on

Example: kafka_default

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'localhost:1234/api/control/{component}/{id}'

200

401

403

500

501

200

No body

OK

Reload gateway component configuration

Issues REFRESH command for [component] and [id] and returns its new settings.

post

/api/control/{component}//{id}

Path parameters

componentanyrequired

Gateway component type to apply command on

Example: system

idanyrequired

Gateway component id to apply command on

Example: kafka_default

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/control/{component}/{id}'

200

401

403

500

501

200

No body

OK

Issue gateway command

Receives [command], [component] (such as system, channel, service, token) and [id] parameters in body to execute REFRESH or SHOW commands.

post

/api/control

Body

commandstring

Example: REFRESH

componentstring

Example: system

idstring

Example: kafka_default

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/control' \
  --header 'Content-Type: application/json' \
  --data '{"command":"REFRESH","component":"system","id":"kafka_default"}'

200

401

403

500

501

200

No body

OK

Command APIs

Command APIs provide ability to centrally issue commands to all runners for their administration. All commands are processed and responded to in an async manner, so their acknowledgement and results are typically reported using a separate API request.

Similar to events, commands also have request metadata, which is enriched using same approach as gateway APIs, with headers and cookies for authentication. Users need to have roles specified for gateway services used by commands to be able to issue them.

Send command to runner(s)

Sends a command provided in request body to the default command service and topic.

post

/api/command/

Body

object

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/command/' \
  --header 'Content-Type: application/json'

200

401

403

500

501

200

No body

OK

Send command to runner(s) thru path

Sends a command provided in request body to the [path] command topic.

post

/api/command/{path}

Path parameters

pathstringrequired

Path for issuing commands

Example: command_backup

Body

object

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/command/{path}' \
  --header 'Content-Type: application/json'

200

401

403

500

501

200

No body

OK

Message APIs

Message APIs provide ability to send messages to any Kafka service and topic for adhoc use cases.

Messages are authenticated using request metadata generated from headers and cookies of the request. Users need to have roles specified for the gateway service specified to be able to send messages.

Send message to topic

Sends a message provided in request body to [topic] on [service]. If [key] is specified, it is used as the message key on target topic, as well as in calculating the partition id.

post

/api/send/{service}//{topic}//{key}

Path parameters

servicestringrequired

Kafka service name to send message

Example: kafka_default

topicstringrequired

Kafka topic name to send message

Example: trigger

keystringrequired

Message key for sending message

Example: 10001

Body

object

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/send/{service}/{topic}/{key}' \
  --header 'Content-Type: application/json'

200

401

403

500

501

200

No body

OK

Send message to topic

Sends a message provided in request body to [topic] on [service] on partition [key] modulo [mod].

post

/api/send/{service}//{topic}/mod/{mod}//{key}

Path parameters

servicestringrequired

Kafka service name to send message

Example: kafka_default

topicstringrequired

Kafka topic name to send message

Example: trigger

keystringrequired

Message key for sending message

Example: 10001

modstringrequired

Module for finding topic partition

Example: 10

Body

object

Responses

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'localhost:1234/api/send/{service}/{topic}/mod/{mod}/{key}' \
  --header 'Content-Type: application/json'

200

401

403

500

501

200

No body

OK