Scalecube Configuration Service API Document

Introduction

The Scalecube Configuration service API offers to create and manage a separate repositories for metadata (entries) record and storage.

Configuration service API supports few connection protocols:

WebSockets
RSocket
HTTP

Highest throughput and lowest latency are achieved by using WebSockets

Any request body should be a valid JSON, non-valid JSON objects will be ignored.

Within the valid JSON please be aware that:

System ignores any additional parameter that was sent on request body but was not specified in this document.
In case of the same multiple parameters (keys) sent with different values, the system will always use the last value provided.

Sandbox

Navigate to Scalecube Sandbox
Set the transport (connection protocol) to be used for (RSocket either WebSocket)
Click on the Settings button then set Sandbox endpoint which is referred to related transport:

WebSocket: wss://configuration-service-ws.genesis.om2.com
RSocket: wss://configuration-service-rs.genesis.om2.com

Enter the message body in the text area
Click on the Connect button and push the Send button
Note: You can import few samples by clicking on Import icon and paste this sample Json file url

How to connect via HTTP will be listed below

General Specifications

WebSockets

Request Parameters

Parameter	Type	Description
q	String	qualifier, contains the method for the specific API call.
sid	Int	stream identifier, for each WebSocket connection this is a unique identifier for the API call. Please note that as long as the sid was not ended (either by the Service or by the consumer) this can’t be used again on the same WebSocket connection
d	Json	data object, contain the request body

{
    "q": "/configuration/createRepository",
    "sid": 1,
    "d": {
        "apiKey": "API-KEY",
        "repository": "REPO-NAME"
    }
}

Success Response
The response will always include the q and sid parameters from the request and the d parameter with the response body.

{
    "q":"/configuration/createRepository",
    "sid":1,
    "d":{}
}

All the streams are short-living thus additional response will be sent promptly upon stream closure with success, this message will include sid with request sid and sig:1.

{ 
  "sig":1, 
  "sid":1 
}

Response With Failure

The response will always include the below parameters:

Parameter	Description
sig	signal will be equal to "2"
q	always /io.scalecube.services.error/`500`
sid	from request
d	data that contain errorCode:`500` and related errorMessage

{ 
   "sig":2, 
   "q":"/io.scalecube.services.error/500", 
   "sid":1, 
   "d": 
     { 
       "errorCode":500, 
       "errorMessage":"Repository with name: 'REPO-NAME' already exists" 
     } 
}

Manual Stream Closure (OPTIONAL since all the streams are short-living thus can't be performed) In order to close active stream need to send a cancel message with sig:3 and sid with the related stream id to be closed.

{ 
    "sig":3, 
    "sid":1
}

sig parameter summary table:

sig	Description
1	Stream closed with success
2	Stream closed with failure
3	Stream was cancelled (closed) due to the consumer request

RSocket

Request / Response / Failure structure are very close to WebSockets

Request

{
    "metadata": {
        "q": "/configuration/createRepository"
    },
    "data": {
        "apiKey": "API-KEY",
        "repository": "REPO-NAME"
    }
}

Successful Response

{
    "data":{},
    "metadata":{
                 "q":"/configuration/createRepository"
    }
}

Response With Failure

{
    "data": {
		"errorCode": 500,
		"errorMessage": "Repository with name: 'REPO-NAME' already exists"
    },
    "metadata": {
		"q": "/io.scalecube.services.error/500"
    }
}

HTTP

All the connectivity is done via HTTPS. Below is to be set for using this protocol properly:

"endpoint url": host address/method.
"method": POST
"headers": Content-Type application/json
"body": request body

Request

POST /configuration/createRepository
Content-Type: application/json
Host: https://configuration-service-http.genesis.om2.com
{"apiKey": "API-KEY", "repository": "REPO-NAME"}

Successful Response

HTTP/1.1 200
status: 200
Date: Tue, 21 May 2019 12:38:14 GMT
Content-Type text/plain; charset=utf-8
content-length: 2
Connection: keep-alive
Vary Accept-Encoding
{}

Response With Failure

HTTP/1.1 500
status: 500
Date: Tue, 21 May 2019 12:40:47 GMT
Content-Type text/plain; charset=utf-8
content-length: 77
Connection: keep-alive
Vary Accept-Encoding
{"errorCode":500,"errorMessage":"Repository with name: 'REPO-NAME' already exists"}

Write API

createRepository

This operation enables to create the specified Repository for collecting and storing the relevant entries. Allowed role: Owner.

Endpoint: /configuration/createRepository

Request Parameters

Parameter	Type	Description
apiKey	String	The requested API key
repository	String	Repository name

WS Samples

Request

{
	"q":"/configuration/createRepository",
	"sid": 1,
	"d":{
	        "apiKey": "API-KEY",
                "repository": "REPO-NAME"   
	}
}

Success Response

{
	"q":"/configuration/createRepository",
	"sid":1,
	"d":{}
}

createEntry

This operation enables to create (insert) only new key/ value entry in the relevant Repository. Allowed roles: Owner or Admin.

Endpoint: /configuration/createEntry

Request Parameters

Parameter	Type	Description
apiKey	String	The requested API key
repository	String	Repository name
key	String	Specified key name for the key/ value entry
value	Json	Specified value for the key/ value entry. Note, this can be an array of Json

Response Parameters

Parameter	Type	Description
version	Integer	`1` fixed version for all new entries

WS Samples

Request

{
	"q":"/configuration/createEntry,
	"sid": 1,
	"d":{
		"apiKey": "API-KEY",
                "repository": "REPO-NAME",
                "key": "KEY-NAME",
                "value": "JSON-DATA"   
	}
}

Success Response

{
	"q":"/configuration/createEntry",
	"sid":1,
	"d":{
		"version":1
	}
}

updateEntry

This operation enables to update a specific key/ entry from particular Repository. Note: By updating entry the version is increased but the previous version remains in the system.

Allowed roles: Owner or Admin.

Endpoint: /configuration/updateEntry

Request Parameters

Parameter	Type	Description
apiKey	String	The requested API key
repository	String	Repository name
key	String	Specified key name for the key/ value entry
value	Json	Specified value for the key/ value entry. Note, this can be an array of Json

Response Parameters

Parameter	Type	Description
version	Integer	New version number for the specific key

WS Samples

Request

{
	"q":"/configuration/updateEntry,
	"sid": 1,
	"d":{
		"apiKey": "API-KEY",
                "repository": "REPO-NAME",
                "key": "KEY-NAME",
                "value": {"NEW":"JSON-DATA"}   
	}
}

Success Response

{
	"q":"/configuration/updateEntry",
	"sid":1,
	"d":
	{
	    "version":7
	}
}

deleteEntry

This operation enables to delete a specific key/ entry from particular Repository. Allowed roles: Owner or Admin.

Endpoint: /configuration/deleteEntry

Request Parameters

Parameter	Type	Description
apiKey	String	The requested API key
repository	String	Repository name
key	String	Specified key name for the key/ value entry

WS Samples

Request

{
	"q":"/configuration/deleteEntry",
	"sid": 1,
	"d":{
		"apiKey": "API-TOKEN",
                "repository": "specifiedRepoName",
                "key": "specifiedKeyName"   
	}
}

Success Response

{
	"q":"/configuration/deleteEntry",
	"sid":1,
	"d":{}
}

Read API

readEntry

This method enables to get a specific entry. By default, it will return the latest version of the key unless specific version was requested.

Allowed roles: Owner or Admin or Member.

Endpoint: /configuration/readEntry

Request Parameters

Parameter	Type	Description
apiKey	String	The requested API key
repository	String	Repository name
key	String	Specified key name for the key/ value entry
version `optional`	Integer	Specific version of the key

Response Parameters

Parameter	Type	Description
value	Json	Specified value for the key/ value entry. Note, this can be an array of Json
key	String	Specified key name for the key/ value entry

WS Samples

Request

{
	"q":"/configuration/readEntry",
	"sid": 1,
	"d":{
                "apiKey": "API-TOKEN",
                "repository": "specifiedRepoName",
                "key": "specifiedKeyName"
                "version": 2
        }
}

Success Response

{
	"q":"/configuration/readEntry",
	"sid":1,
	"d":{
        "value": {
                   "name": "Euro",
                   "instrument": "EUR",
                   "DecimalPrecision" : "4",
                   "Rounding": "down"
                 },
        "key": "specifiedKeyName"
        }
    }
}

readList

This method enables to get all entries for the required Repository. By default, it will return the latest version of the keys unless specific version was requested, in such case only keys with the requested version will be returned.

Allowed roles: Owner or Admin or Member.

Endpoint: /configuration/readList

Request Parameters

Parameter	Type	Description
apiKey	String	The requested API key
repository	String	Repository name
version `optional`	Integer	Specific version of the keys (only if specific version is required). If empty the latest version of each key is returned.

Response Parameters

Parameter	Type	Description
JsonArray	Json[]	List of all key/value entries in the repository (Array of Json)

WS Samples

Request

{
	"q":"/configuration/readList",
	"sid": 1,
	"d":{
                 "apiKey": "API-KEY",
                 "repository": "REPO-NAME"
        }
}

Success Response

{
	"q":"/configuration/readList",
	"sid":1,
	"d":[
		{
			"value": {
				"value": 11,
				"text": "text11"
			},
			"key": "Key2"
		},
		{
			"value": {
				"value": 3,
				"text": "text3"
			},
			"key": "Key1"
		}
	]
}

readEntryHistory

This method enables to get all the versions per a specific entry. Allowed roles: Owner or Admin or Member.

Endpoint: /configuration/readEntryHistory

Request Parameters

Parameter	Type	Description
apiKey	String	The requested API key
repository	String	Repository name
key	String	Specified key name for the key/ value entry

Response Parameters

Parameter	Type	Description
JsonArray	Json[]	List of all key/value entries in the repository (Array of Json)

WS Samples

Request

{
	"q":"/configuration/readEntryHistory",
	"sid": 1,
	"d":{
                 "apiKey": "API-KEY",
                 "repository": "REPO-NAME"
        }
}

Success Response

{
	"q":"/configuration/readEntryHistory",
	"sid":1,
	"d":[
			{
				"version": 1,
				"value": {
					"value": 1,
					"text": "text1"
				}
			},
			{
				"version": 2,
				"value": {
					"value": 2,
					"text": "text2"
				}
			},
			{
				"version": 3,
				"value": {
					"value": 3,
					"text": "text3"
				}
			}
		]
}

Error Codes

The below error message are common for the configuration service API. Error Codes

Code	Message	Description
500	`Token verification failed`	invalid Token (API key)
500	`Permission denied`	invalid permission level for the specified API key
500	`Please specify 'apiKey'`	required field is missed
500	`Please specify 'repository'`	required field is missed
500	`Please specify 'key'`	required field is missed
500	`Repository with name: 'REPO-NAME' already exists`	specified repository currently in use for the particular organization
500	`Repository 'REPO-NAME' key 'KEY-NAME' already exists`	specified key already exists in the particular repository
500	`Repository 'REPO-NAME' not found`	specified repository doesn't exist
500	`Repository 'REPO-NAME' or its key 'KEY-NAME' not found`	specified repository either key doesn't exist in the particular repository
500	`Key 'KEY-NAME' version '999999' not found`	specified version number doesn't exist in the particular repository (applied only for `readEntry` method)
500	`Failed to decode data on message q=/configuration/readEntry`	version filed isn't the `int` datatype
500	`Failed to decode data on message q=/configuration/readList`	version filed isn't the `int` datatype

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Scalecube Configuration Service API Document

Table of Contents

Introduction

Sandbox

WebSockets

RSocket

HTTP

Write API

createRepository

createEntry

updateEntry

deleteEntry

Read API

readEntry

readList

readEntryHistory

Error Codes

Clone this wiki locally