API Services – Machinations Developer Portal

Web Socket communication

The Machinations API is organized around socket.io. Our API accepts & returns JSON-encoded request/responses and uses the WebSocket Protocol

Behind these APIs there is a software layer connecting your Machinations Public Diagrams to allow your socket.io client to get diagram changes.

You can use any web socket client compatible with socket.io.

Working with the Machinations API

Authentication

You can get a User Key from your Machinations account, under your Profile Picture > Settings > Account Details.

Keep your credentials secure! Do not share your secret API keys in publicly accessible spaces such as GitHub, client-side code, and so forth. All requests must be made over WSS (WebSocket Secure). Calls made over plain WS will fail. API requests without the User Key will also fail. Provide your User Key as a parameter of connection to Machinations. You do not need to provide a password.

Code example:

Node.JS

// 
const io = require('socket.io-client');
const options = {
  reconnect: false,
  forceNew: true,
  transports: ['websocket']
}
const serverAdd = 'wss://api.my.machinations.io?userkey=LoremIpsum1234qwer';
const socket = io(serverAdd, options);
socket.on("connect", () => {
  // API communication
})

const io = require('socket.io-client');

const options = {

reconnect: false,

forceNew: true,

transports: ['websocket']

}

const serverAdd = 'wss://api.my.machinations.io?userkey=LoremIpsum1234qwer';

const socket = io(serverAdd, options);

socket.on("connect", () => {

// API communication

})

C# (specific to Unity Socket IO Component)

private SocketIOComponent socket;
socket = go.GetComponent<SocketIOComponent>();
socket.SetUserKey(userKey);
socket.Init();
socket.On(SyncMsgs.RECEIVE_OPEN, OnSocketOpen);
socket.On(SyncMsgs.RECEIVE_AUTH_SUCCESS, OnAuthSuccess);
//... other event handlers
socket.Connect();

private SocketIOComponent socket;

socket = go.GetComponent<SocketIOComponent>();

socket.SetUserKey(userKey);

socket.Init();

socket.On(SyncMsgs.RECEIVE_OPEN, OnSocketOpen);

socket.On(SyncMsgs.RECEIVE_AUTH_SUCCESS, OnAuthSuccess);

//... other event handlers

socket.Connect();

In case of an invalid User Key, the client receives an error response and the connection is terminated.

Through the authenticated socket, clients can send/receive messages using the JSON format.

Connection to the Machinations Diagram

In Machinations, you can create diagrams and generate one Token per diagram.

Provide the diagram Token to the authorize call: JSON-schema

Example: node.js

socket.on("connect", () => {
  socket.emit('api-authorize', { diagramToken: 'LoremIpsum1234qwer', gameName: 'Ruby Game' });
});

socket.on("connect", () => {

socket.emit('api-authorize', { diagramToken: 'LoremIpsum1234qwer', gameName: 'Ruby Game' });

});

Example Machinations responses:

deny response:

// you do not have a valid token or user has no rights  
// user is identified based on user key
socket.on('api-auth-deny', (msg) => {

}

// you do not have a valid token or user has no rights

// user is identified based on user key

socket.on('api-auth-deny', (msg) => {

}

success response

//
socket.on('api-auth-success', (msg) => {

}

socket.on('api-auth-success', (msg) => {

}

Message format: JSON-schema

Connect Diagram Elements

From your Machinations diagram, get the Node ID and properties from the Properties Panel, by selecting the Node.

Based on the Node ID & Properties, the client is able to gate the current value & changes of properties during diagram edit.

Initialization request

The initialization request can be sent at any time and the communication list will be changed.

Example: node.js

socket.on('api-auth-success', (msg) => {
  const gameData = {
  diagramToken: diagraToken,
  machinationsIDs:[
    {id: 19, props: ['label', 'activation','action', 'resources', 'capacity' , 'overflow']},
    {id: 74, props: ['label', 'activation', 'action', 'resources', 'capacity', 'overflow'] },
  ]
  };
  socket.emit('game-init', gameData);
});

socket.on('api-auth-success', (msg) => {

const gameData = {

diagramToken: diagraToken,

machinationsIDs:[

{id: 19, props: ['label', 'activation','action', 'resources', 'capacity' , 'overflow']},

{id: 74, props: ['label', 'activation', 'action', 'resources', 'capacity', 'overflow'] },

]

};

socket.emit('game-init', gameData);

});

Machinations will respond with the properties values:

Example: node.js

//
socket.on('game-init', (msg) => {
    // nodes properties values 
});

socket.on('game-init', (msg) => {

// nodes properties values

});

Example: JSON-schema response

{
    diagramElements: [
        {
            id:'19',
            type: 'Pool',
            label: 23,
            activation: 'passive',
            action: 'pull-all',
            resources: 281,
            capacity: -1,
            overflow: 'block'
        },
        {
            id: '74',
            type: 'Pool',
            label: 'Speed',
            activation: 'passive',
            action: 'push-any',
            resources: 48,
            capacity: 296,
            overflow: 'block'
        }
    ]
}

{

diagramElements: [

{

id:'19',

type: 'Pool',

label: 23,

activation: 'passive',

action: 'pull-all',

resources: 281,

capacity: -1,

overflow: 'block'

{

id: '74',

type: 'Pool',

label: 'Speed',

activation: 'passive',

action: 'push-any',

resources: 48,

capacity: 296,

overflow: 'block'

}

]

}

While the socket is open, the client will receive, from Machinations, any properties changes but only the ones reflected on the init list.

Example: node.js

socket.on('diagram-elements-updated', (msg) => { 
  // nodes properties updates 
});

socket.on('diagram-elements-updated', (msg) => {

// nodes properties updates

});

Example: JSON-schema response

//
{ diagramElements: [ { id: '19', resources: 283 } ] }
...
{ diagramElements: [ { id: '74', resources: 50 } ] }

{ diagramElements: [ { id: '19', resources: 283 } ] }

...

{ diagramElements: [ { id: '74', resources: 50 } ] }

Communication Node & Properties List

An array of elements (node id & properties) set up at initialization request (‘game-init’)
The client will receive a property update (‘diagram-elements-updated’ event type) only if the property(& node id) is on the list
This list can be changed with an initialization request (‘game-init’), at any time

Example of a JSON-schema

// 
[ 
{id: 62, props: ['label', 'activation']},
{id: 65, props: ['label', 'transfer', 'limitis']},
{id: 19, props: ['label', 'activation','action', 'resources', 'capacity' , 'overflow']}, 
{id: 74, props: ['label', 'activation', 'action', 'resources', 'capacity', 'overflow'] },
]

[

{id: 62, props: ['label', 'activation']},

{id: 65, props: ['label', 'transfer', 'limitis']},

{id: 19, props: ['label', 'activation','action', 'resources', 'capacity' , 'overflow']},

{id: 74, props: ['label', 'activation', 'action', 'resources', 'capacity', 'overflow'] },

]

Named versions

This request asks for the list of named versions for a diagram. The diagram will be identified by diagramToken.

socket.emit('get-versions', { diagramToken: 'LoremIpsum1234qwer', gameName: 'Ruby Game' });

1	socket.emit('get-versions', { diagramToken: 'LoremIpsum1234qwer', gameName: 'Ruby Game' });

The response has the following format:

{
    versions: [
        {
            name:'My latest version',
            timestamp: 523456789,
        },
        {
            name:'Some other version',
            timestamp: 456789123,
        }
    ]
}

{

versions: [

{

name:'My latest version',

timestamp: 523456789,

{

name:'Some other version',

timestamp: 456789123,

}

]

}

Get all diagram elements

This request asks for a list of all elements in a diagram. The diagram will be identified by diagramToken.

socket.emit('get-all-elements', { diagramToken: 'LoremIpsum1234qwer', gameName: 'Ruby Game' });

1	socket.emit('get-all-elements', { diagramToken: 'LoremIpsum1234qwer', gameName: 'Ruby Game' });

The response has the following format:

{
    diagramElements: [
        {
            id:'19',
            type: 'Pool',
            label: 23,
            activation: 'passive',
            action: 'pull-all',
            resources: 281,
            capacity: -1,
            overflow: 'block'
        },
        {
            id: '74',
            type: 'Pool',
            label: 'Speed',
            activation: 'passive',
            action: 'push-any',
            resources: 48,
            capacity: 296,
            overflow: 'block'
        }
    ]
}

{

diagramElements: [

{

id:'19',

type: 'Pool',

label: 23,

activation: 'passive',

action: 'pull-all',

resources: 281,

capacity: -1,

overflow: 'block'

{

id: '74',

type: 'Pool',

label: 'Speed',

activation: 'passive',

action: 'push-any',

resources: 48,

capacity: 296,

overflow: 'block'

}

]

}

Events types

Send (socket.emit …)
- ‘api-authorize’ – Authorizing diagram connection
- ‘game-init’ – Request Nodes properties from a diagram
- ‘get-versions’ – Request version history from a diagram.

Receive (socket.on …)
- api-auth-deny’ – Authorization denied. You do not have a valid Token or user has no rights (user is identified based on the User Key)
- ‘api-auth-success’ – Successful authorization
- ‘game-init’ – Response at initialization request
- ‘diagram-elements-updated’ – Sent when an element from the communication list is changed on machinations.io‘s side
- ‘api-error’ – Machinations API error
- ‘error’ – Socket.io error

Available Properties

id – Integer (node id)
type – String (available types: “Source”, “Drain”, “Pool”, “Gate”, “Trader”, “Delay”, “Converter”, “Register”, “End Condition”, “State Connection”, “Resource Connection”, “Text”, “Group”)
label – String (machations.io label / machinations.io nodes label)
activation – String ( machinations.io activation see activation modes )
action – String (machinations.io action)
resources – Integer (machinations.io resources)
capacity – Integer (machinations.io capacity)
overflow – String (machinations.io overflow)
limits – Integers (machinations.io registers limits)
transfer – String (connection transfer)

Error Codes:

415050 – Invalid or missing User Key
415051 – Error while validating User Key
415070 – Missing diagram Token
415071 – Invalid diagram Token
415072 – Error during validating diagram Token
415073 – Parameter diagramToken not present in the JSON request
415090 – Web socket not authenticated
415091 – Web socket not authorized
4150110 – Diagram parse error
415130 – Parameter gameData not present in the JSON request
415131 – Parameter machinationsIDs not present in the JSON request