View source for Connecting Resonite to other applications

When creating items and worlds within Resonite, you may want to connect Resonite to the outside world. To applications, software and systems that are outside of it. This guide will provide some information on how you can achieve that.

== Example Scenarios ==
Some example things you might want to do this with are:
* Communicating with Web Servers
* Talking to Real world Hardware or devices such as Heart Rate Sensors, Lights or Sound Equipment
* Receiving data such as stock information, the weather and more

== Options ==
You have a number of options to achieve communication with other applications. With all of these options do remember that Resonite '''does not''' support JSON or Collections/Arrays so you will have to handle parsing these yourself within [[ProtoFlux]].

=== Webserver Communication using HTTP ===

Resonite has two nodes that can allow you to make HTTP Requests:
* [[ProtoFlux:GET String|HTTP GET]] - Submits an HTTP GET Request
* [[ProtoFlux:POST String|HTTP POST]] - Submits an HTTP POST Request 

You can use these to communicate with any HTTP capable webserver, API or system. 

=== Web Socket Communication ===
ProtoFlux has [[WebSocket| WebSocket capabilities]]. These allow Resonite to communicate with any WebSocket capable server. This is useful for real time communication between Resonite and an Application.

=== Sending other Protocols over WebSockets ===
While Resonite only supports [[HTTP]], [[WebSocket|WebSockets]] and [[OSC]] you can send messages over WebSockets which resemble or contain messages in other protocols. Users have done this with:
* DMX
* MIDI

=== Using a WebSocket / HTTP Proxy ===

You can also use WebSockets or HTTP as a proxy to communicate to another device. Users have done this with:
* Heart Rate Sensors
* Calendars
* Complex APIs that needed simplifying

=== Using Plugins ===
Resonite has [[Plugins]] which allow you to write custom functionality into Resonite. This functionality can be vast and varied as you have full implementation control in C#. When you use plugins you will be isolated from the rest of the Resonite Community as they will only be able to join your sessions if they have the same Plugins installed. Please see the [[Plugins|plugin page]] for more information.

== Security / Consent ==
Always consider Security, talking to outside systems can open up all sorts of security issues.
As of version <code>2024.4.26.1258</code> be aware that:
* HTTP requests and websockets cannot be authenticated. (Userinfo in URIs like <code>https://'''''user:password'''''@host/</code> will be ignored!)
* Without a permission system the World Model is open to everyone. With enough effort any user can read local values and trigger ProtoFlux of another.
This means that at this time anything involving Payments, Passwords or personal information is not recommended.

Additionally, outside connections via HTTP and WebSockets are controlled by a User's Consent, They can block and allow access to specific domain names and servers. Always use the [[ProtoFlux:Is Host Access Allowed|Is Host Access Allowed]] and [[ProtoFlux:Request Host Access|Request Host Access]] Nodes to check if a User has blocked a connection and to request access to a host. When requesting access, please specify a logical reason.

If a user has blocked access, try to make your systems gracefully fail with a clear message about what is going on.

== Recommendations ==
When deciding what to do here, it's entirely up to you but some recommendations are presented here to assist you in making a decision.
* Only use WebSockets if you need real time communication - WebSockets have extra overhead for both servers and clients/Resonite users. If you just need to make requests and receive responses consider HTTP instead.
* Ensure that you're running the requests / connections from the right users. Connections need to be made from a user. For example when you make a request a single user is in charge of running that request. Make sure this is the correct user and that you're not running requests for more than one user.