Home

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

get

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

Path parameters
channelstringRequired

Gateway channel for execution

Example: crud
pathstringRequired

Path for calling specific action / saga on gateway channel

Example: product
Responses
200
OK
get
GET 1234/api/request/{channel}/{path} HTTP/1.1
Host: 
Accept: */*

No content

Request with "data" URL parameter as contents

get

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

Path parameters
channelstringRequired

Gateway channel for execution

Example: crud
pathstringRequired

Path for calling specific action / saga on gateway channel

Example: product
Query parameters
datastringOptional

Json string representation of a request

Example: {origin:{}, auth:{}, payload:{}}
Responses
200
OK
get
GET 1234/api/request/full/{channel}/{path} HTTP/1.1
Host: 
Accept: */*

No content

Request with "data" URL parameter as base64 contents

get

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

Path parameters
channelstringRequired

Gateway channel for execution

Example: crud
pathstringRequired

Path for calling specific action / saga on gateway channel

Example: product
Query parameters
datastringOptional

Base64 encoded Json string representation of a request

Example: e29yaWdpbjp7fSwgYXV0aDp7fSwgcGF5bG9hZDp7fX0=
Responses
200
OK
get
GET 1234/api/request/full/e/{channel}/{path} HTTP/1.1
Host: 
Accept: */*

No content

Request with body for payload

post

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

Path parameters
channelstringRequired

Gateway channel for execution

Example: crud
pathstringRequired

Path for calling specific action / saga on gateway channel

Example: product
Body
objectOptional
Responses
200
OK
post
POST 1234/api/request/{channel}/{path} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
No content

Request with body for full details

post

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

Path parameters
channelstringRequired

Gateway channel for execution

Example: crud
pathstringRequired

Path for calling specific action / saga on gateway channel

Example: product
Body
originobjectOptional
authobjectOptional
payloadobjectOptional
Responses
200
OK
post
POST 1234/api/request/full/{channel}/{path} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "origin": {},
  "auth": {},
  "payload": {}
}
No content

Request with body for base64 encoded details

post

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.

Path parameters
channelstringRequired

Gateway channel for execution

Example: crud
pathstringRequired

Path for calling specific action / saga on gateway channel

Example: product
Body
stringOptional

Base64 encoding of Json body with origin, auth and payload

Responses
200
OK
post
POST 1234/api/request/full/e/{channel}/{path} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 6

"text"
No content

Request with body for payload

put

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

Path parameters
channelstringRequired

Gateway channel for execution

Example: crud
pathstringRequired

Path for calling specific action / saga on gateway channel

Example: product
Body
objectOptional
Responses
200
OK
put
PUT 1234/api/request/{channel}/{path} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
No content

Request with body for payload

patch

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

Path parameters
channelstringRequired

Gateway channel for execution

Example: crud
pathstringRequired

Path for calling specific action / saga on gateway channel

Example: product
Body
objectOptional
Responses
200
OK
patch
PATCH 1234/api/request/{channel}/{path} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
No content

Request with URL parameters for payload

delete

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

Path parameters
channelstringRequired

Gateway channel for execution

Example: crud
pathstringRequired

Path for calling specific action / saga on gateway channel

Example: product
Responses
200
OK
delete
DELETE 1234/api/request/{channel}/{path} HTTP/1.1
Host: 
Accept: */*

No content

Auth APIs

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

New user registration

post

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.

Path parameters
channelstringRequired

Gateway channel for authentication

Example: crud
typestringRequired

Type of authentication to use

Example: customer
Query parameters
thrustringOptional

Whether request should be passed on to authentication servers too

Default: falseExample: true
Responses
200
OK
post
POST 1234/api/auth/register/{channel}/{type} HTTP/1.1
Host: 
Accept: */*

No content

Existing user login

post

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.

Path parameters
channelstringRequired

Gateway channel for authentication

Example: crud
typestringRequired

Type of authentication to use

Example: customer
Query parameters
thrustringOptional

Whether request should be passed on to authentication servers too

Default: falseExample: true
cookiestringOptional

Whether tokens should be returned in cookies

Default: falseExample: true
rememberstringOptional

Whether tokens should have longer expirations

Default: falseExample: true
Responses
200
OK
post
POST 1234/api/auth/login/{channel}/{type} HTTP/1.1
Host: 
Accept: */*

No content

User tokens refresh

post

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

Path parameters
channelstringRequired

Gateway channel for authentication

Example: crud
typestringRequired

Type of authentication to use

Example: customer
Query parameters
cookiestringOptional

Whether tokens should be returned in cookies

Default: falseExample: true
Responses
200
OK
post
POST 1234/api/auth/refresh/{channel}/{type} HTTP/1.1
Host: 
Accept: */*

No content

Existing user logout

post

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.

Path parameters
channelstringRequired

Gateway channel for authentication

Example: crud
typestringRequired

Type of authentication to use

Example: customer
Query parameters
thrustringOptional

Whether request should be passed on to authentication servers too

Default: falseExample: true
cookiestringOptional

Whether tokens should be returned in cookies

Default: falseExample: true
Responses
200
OK
post
POST 1234/api/auth/logout/{channel}/{type} HTTP/1.1
Host: 
Accept: */*

No content

Existing user removal

post

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.

Path parameters
channelstringRequired

Gateway channel for authentication

Example: crud
typestringRequired

Type of authentication to use

Example: customer
Query parameters
thrustringOptional

Whether request should be passed on to authentication servers too

Default: falseExample: true
cookiestringOptional

Whether tokens should be returned in cookies

Default: falseExample: true
Responses
200
OK
post
POST 1234/api/auth/delete/{channel}/{type} HTTP/1.1
Host: 
Accept: */*

No content

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

post

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.

Path parameters
channelstringRequired

Gateway channel as origin of event

Example: crud
pathstringRequired

Path for registering specific action / saga on gateway channel

Example: product
Body
objectOptional
Responses
200
OK
post
POST 1234/api/track/{channel}/{path} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
No content

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

get

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

Path parameters
servicestringRequired

File system to use for operations

Example: default_hdfs
Responses
200
OK
get
GET 1234/api/file/{service} HTTP/1.1
Host: 
Accept: */*

No content

Downloads a selected file

get

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

Path parameters
servicestringRequired

File system to use for operations

Example: default_hdfs
filePathstringRequired

Relative path to selected file

Example: test/sample.json
Responses
200
OK
get
GET 1234/api/file/{service}/{filePath} HTTP/1.1
Host: 
Accept: */*

No content

Upload unnamed file

post

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

Path parameters
servicestringRequired

File system to use for operations

Example: default_hdfs
Body
string · binaryOptional
Responses
200
OK
post
POST 1234/api/file/{service} HTTP/1.1
Host: 
Content-Type: application/octet-stream
Accept: */*
Content-Length: 8

"binary"
No content

Upload named file

post

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

Path parameters
servicestringRequired

File system to use for operations

Example: default_hdfs
filePathstringRequired

Relative path to selected file

Example: test/sample.json
Body
string · binaryOptional
Responses
200
OK
post
POST 1234/api/file/{service}/{filePath} HTTP/1.1
Host: 
Content-Type: application/octet-stream
Accept: */*
Content-Length: 8

"binary"
No content

Deletes a selected file

delete

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

Path parameters
servicestringRequired

File system to use for operations

Example: default_hdfs
filePathstringRequired

Relative path to selected file

Example: test/sample.json
Responses
200
OK
delete
DELETE 1234/api/file/{service}/{filePath} HTTP/1.1
Host: 
Accept: */*

No content

Control APIs

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

Show gateway component configuration

get

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

Path parameters
componentanyRequired

Gateway component type to apply command on

Example: system
idanyRequired

Gateway component id to apply command on

Example: kafka_default
Responses
200
OK
get
GET 1234/api/control/{component}/{id} HTTP/1.1
Host: 
Accept: */*

No content

Reload gateway component configuration

post

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

Path parameters
componentanyRequired

Gateway component type to apply command on

Example: system
idanyRequired

Gateway component id to apply command on

Example: kafka_default
Responses
200
OK
post
POST 1234/api/control/{component}/{id} HTTP/1.1
Host: 
Accept: */*

No content

Issue gateway command

post

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

Body
commandstringOptionalExample: REFRESH
componentstringOptionalExample: system
idstringOptionalExample: kafka_default
Responses
200
OK
post
POST 1234/api/control HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "command": "REFRESH",
  "component": "system",
  "id": "kafka_default"
}
No content

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)

post

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

Body
objectOptional
Responses
200
OK
post
POST 1234/api/command/ HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
No content

Send command to runner(s) thru path

post

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

Path parameters
pathstringRequired

Path for issuing commands

Example: command_backup
Body
objectOptional
Responses
200
OK
post
POST 1234/api/command/{path} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
No content

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

post

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.

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
objectOptional
Responses
200
OK
post
POST 1234/api/send/{service}/{topic}/{key} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
No content

Send message to topic

post

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

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
objectOptional
Responses
200
OK
post
POST 1234/api/send/{service}/{topic}/mod/{mod}/{key} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
No content
PreviousGateway TokensNextOpenAPI Specification

Last updated