META API Protocol

Description of communication protocol.

Communication

META API is using WebSocket for bi-directional communication between server and client.

  • MessagePack is used for message encoding
  • Server responds to RPC calls and can publish message to channels
  • Client can call remote methods and can subscribe to channels

Message broker

Many components needs realiable message delivery. META Stack implements message broker service.

  • Each API server connects to message broker and is waiting for incoming RPC requests
  • Each API client connects to message broker and send requests
  • Message broker handles channel subscriptions and delivers published messages
  • API server also acts as client so it can subscribe to other channels and can call other services

Request

Method call request

{
    "r": 101,
    "i": "u36dHjkFr34",
    "s": "customerdb",
    "p": [ "customers", 42, "@get" ],
    "a": [
        { "properties": [
            "first_name"
            "last_name"
        ] }
    ]
}
Property name Type Description
r integer Request type - 101 = Method call
i string Unique request ID for client. Response will be identified by this ID.
s string Service name
p array Request path
a array Method arguments

Request path must follow this rules:

  • Method is prefixed by @
  • If no method is specified then endpoint must return property schema

Subscribe & unsubscribe request

{
    "r": 102,
    "i": "u36dHjkFr64",
    "c": "customerdb:/customers/42"
}
Property name Type Description
r integer Request type - 102 = Subscribe request
i string Unique request ID for client. Response will be identified by this ID.
c string Channel name
{
    "r": 103,
    "i": "u36dHjkFr96",
    "c": "customerdb:/customers/42"
}
Property name Type Description
r integer Request type - 103 = Unsubscribe request
i string Unique request ID for client. Response will be identified by this ID.
c string Channel name

Publish request

{
    "r": 104,
    "i": "u36dHjkFr12",
    "c": "customerdb:/customers/42",
    "d": {
        "first_name": "John",
        "last_name": "Doe"
    },
    "t": 3600
}
Property name Type Description
r integer Request type - 104 = Publish request
i string Unique request ID for client. Response will be identified by this ID.
c string Channel name
d mixed Published data
t integer Message lifetime (TTL) in seconds. Message will be removed from delivery queue for subscriber that doesn`t pick up message within specified time.

Authorization / registration request

{
    "r": 106,
    "i": "u36dHjkFr42",
    "u": "customerdb",
    "s": "uHd3Dkdf2DaF6="
}
Property name Type Description
r integer Request type - 105 = Authorization request
i string Unique request ID for client. Response will be identified by this ID.
u string Client / server ID (service name)
s string Secret

Response

Method call result

{
    "r": 201,
    "i": "u36dHjkFr34",
    "d": {
        "first_name": "John",
        "last_name": "Doe"
    }
}
Property name Type Description
r integer Response type - 201 = Method call result
i string Unique request ID for client.
d mixed Result data

Subscribe & unsubscribe confirmation

{
    "r": 202,
    "i": "u36dHjkFr64"
}
Property name Type Description
r integer Response type - 202 = Subscribe successfull
i string Unique request ID for client.
{
    "r": 203,
    "i": "u36dHjkFr96"
}
Property name Type Description
r integer Response type - 203 = Unsubscribe successfull
i string Unique request ID for client.

Publish confirmation

{
    "r": 204,
    "i": "u36dHjkFr12",
    "c": 3
}
Property name Type Description
r integer Response type - 204 = Published
i string Unique request ID for client.
c integer Count of subscribers

Incoming message

{
    "r": 205,
    "c": "customerdb:/customers/42",
    "d": {
        "first_name": "John",
        "last_name": "Doe"
    },
}
Property name Type Description
r integer Response type - 205 = Incoming published message
c string Channel name
d mixed Published data

Authorization / registration request

{
    "r": 206,
    "i": "u36dHjkFr42"
}
Property name Type Description
r integer Response type - 206 = Authorization response
i string Unique request ID for client.

Error response

{
    "r": 500,
    "i": "u36dHjkFr34",
    "e": "InvalidArguments",
    "m": "You must specify all required arguments.",
    "d": {
        "0": "Value"
    }
}
Property name Type Description
r integer Response type - 500 = Generic error
i string Unique request ID for client.
e string Error name
m string Error message
d object Optional descriptive data

Endpoint schema

Endpoint schema describes object properties and methods.

  • Properties with $ prefix are descriptive (meta) values
  • Properties with @ prefix describes method
  • Other properties describes endpoint (object) properties
  • Structure of properties depends on it`s purpose and interface
{

    "$name": "Customers",
    "$implements": [ "Collection" ],
    "$title": "Customers",
    "$description": "List of customers",
    "$icon": "user",
    
    "$record": {

        "$name": "CustomerRecord",
        "$implements": [ "Record" ],
        "$title": "Customer",
        "first_name": {
            "$name": "FirstName",
            "$implements": [ "TextProperty" ],
            "$title": "First name",
            "@get": {
                "$arguments": [],
                "$return": "string"
            },
            "@set": {
                "$arguments": [
                    {
                        "name": "value",
                        "type": "string"
                    }
                ]
            }
        },
        "last_name": "..."

    },

    "@get": {
        "$title": "Get records",
        "$arguments": [
            "query": "object",
            "sort": "object",
            "properties": "object"
        ],
        "$return": "CollectionResult"
    },

    "@create": {
        "$title": "Create new customer",
        "$arguments": [ "CustomerRecord" ],
        "$return": "CustomerRecord"
    }

}

Object properties

Property name Type Description
$name string Camel-case schema identifier
$implements array Array of implemented interfaces
$title (optional) string User-friendly endpoint title
$description (optional) string User-friendly description
$icon (optional) string MDI icon used by API console

Method properties

Property name Type Description
$title (optional) string User-friendly method name
$description (optional) string User-friendly method description
$icon (optional) string MDI icon used by API console
$arguments (optional) array Array of accepted arguments in format name: <name>, type: <data type>
$return (optional) string Data type of returned value - can be object schema

Property definition

Each object property is specified by another schema of that property. Object must describe at least one level of it`s properties.

Collection interface

Collection interface for example specifies $record meta property which describes collection record properties and methods.

Table of request and response codes

Code Description
Request
101 Method call
102 Subscribe
103 Unsubscribe
104 Publish
105 Authorize
Success response
201 Method result
202 Subscription confirmation
203 Unsubscribe confirmation
204 Publish confirmation - message has been realiable equeued
205 Incoming published message
206 Authorization successfull
Error response
500 Generic error

Codes may change.