API Services

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

C# (specific to Unity Socket IO Component)

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

Example Machinations responses:

  • deny response: 
  • success response 

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

  • Machinations will respond with the properties values: 

Example: node.js

Example: JSON-schema response

 

  • 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

Example: JSON-schema response

 

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

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 

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