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
|
1 2 3 4 5 6 7 8 9 10 11 12 |
// 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)
|
1 2 3 4 5 6 7 8 |
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.
Connected to the Machinations Diagram
In Machinations, you can create diagrams and generate one Token/diagram.
Provide the diagram Token to the authorize call: JSON-schema
Example: node.js
|
1 2 3 4 |
// socket.on("connect", () => { socket.emit('api-authorize', { diagramToken: 'LoremIpsum1234qwer', gameName: 'Ruby Game' }); }); |
Example Machinations responses:
- deny response:
|
1 2 3 4 5 6 |
// 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
|
1 2 3 4 |
// socket.on('api-auth-success', (msg) => { } |
Message format: JSON-schema
Use Diagram Properties
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
|
1 2 3 4 5 6 7 8 9 10 11 |
// 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
|
1 2 3 4 |
// socket.on('game-init', (msg) => { // nodes properties values }); |
Example: JSON-schema response
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
// { 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
|
1 2 3 4 |
// socket.on('diagram-elements-updated', (msg) => { // nodes properties updates }); |
Example: JSON-schema response
|
1 2 3 4 |
// { 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
|
1 2 3 4 5 6 7 |
// [ {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'] }, ] |
Events types
- Send (socket.emit …)
- ‘api-authorize’ – Authorizing diagram connection
- ‘game-init’ – Request Nodes properties 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
diagramTokennot present in the JSON request - 415090 – Web socket not authenticated
- 415091 – Web socket not authorized
- 4150110 – Diagram parse error
- 415130 – Parameter
gameDatanot present in the JSON request - 415131 – Parameter
machinationsIDsnot present in the JSON request