Examples

Usage

The examples have been included in the package and are imported when the Rest Server package is installed. They can be found in the package directory (usually de.bearo.restserver) in the subdirectory Samples.

Example Description

Note: In all examples the Http Methods are not chosen according to the REST standard or best practices, just for ease of use for the user.

Simple REST Server Example

Simple REST Server usage. This example has the following endpoints

GET /position:
- Returns the current position of the Cube (rest controlled) game object: {"x":0, "y":0, "z":0}
- If a query parameter is given, like http://localhost:8080/position?x=3&y=-2, then the Game object is moved to that position
POST /position:
- Accepts json in the form {"x":0, "y":0, "z":0} and sets the position of the Cube (rest controlled) game object to the given one. Missing coordinates will be interpreted as zero.
GET /triggeranimation:
- Moves the game object Cube (rest controlled) on the positive x-axis over 10 seconds.

Stream Deck

This shows how Unity can be easily controlled with a Stream Deck (or similar). The Stream Deck has a built-in method to call GET endpoints (System -> Webpage, check “Get request in background”). This example has the following endpoint:

GET /spawn:
- Spawns one sphere that bounces through the scene.
GET /spawnMultiple:
- Spawns minimum one sphere, or the amount that was given via the request. For example http://localhost:8080/spawnMultiple?count=100

Twitch Overlay

This shows how a Twitch Overlay for OBS (or similar apps) can be done. The background is a uniform color, that can be removed in OBS. The scene could easily be controlled via a Stream Deck. This example has the following endpoint:

GET /new_follower:
- Shows the text “New Follower!” for 5 seconds

Simple VS Example (Visual Scripting)

This shows how visual scripting can be used. The background is a uniform color, that can be removed in OBS. The scene could easily be controlled via a Stream Deck. This example has been created with visual scripting and exposes the following endpoint:

GET /move:
- Changes the material of the game object and moves it around randomly.

Animation Interlock Example

Shows the usage of the new SimpleInterlock class, which helps implementations where repeated requests against the same endpoint do not restart a animation while it’s running. With Disable Interlock the effects without the Interlock class can be experienced and how the animation can be made look broken.

GET /move:
- Changes the material of the game object and moves it around randomly.

Binary Example

Shows the implementation of an endpoint which let the user download an image

GET /image:
- Displays the image of a Nyan cat

Static Content Example

The static content example shows a simple angular application that is served using the rest server (compressed in the sample-app.zip). The app allows to show/hide a cube. Note that the app is shared with the websocket example and the websocket buttons/text is not working in this example.

GET / (and more):
- Retrieves the example javascript app from the sample-app.zip. To aid navigation, every path that can’t be found will be redirected to the main /index.html.
GET /static/:
- Returns a simple text file served also as static content.

Reverse Proxy Example

This example implements a reverse proxy. In this case it reverse proxies this documentation pages.

GET /.*:
- Redirects the request to this documentation site.

Simple Form Upload Example

Note that the parser using in this example is a custom parser that is only able to use a simple subset of the multipart/form-data standard. If you need additional features you can of course suggest them, but the parser will not support every feature of the standard. If you need all features, please use an established implementation.

This example shows a simple form upload (multipart/form-data) upload by using a simple, custom parser.

GET /:
- Simple index.html that contains an upload form
POST /upload:
- Upload endpoint. Uses the first binary data element and displays it as texture

WebSocket Example

Simple example showing the basic usage of a websocket. The websocket delivers the current position of the cube. The static content auto endpoint is used to serve a simple angular web application that connects to the websocket. Note that the app is re-used from the static content example and only the websocket part is working.

GET /:
- Simple index.html that contains the static content example app.
GET /websocket/cube_updates:
- Websocket endpoint

WebView Example

This example shows how a web view could use the rest server as backend api in mobile applications (iOS and Android). Here it’s shown with the UniWebView, but can be used with any other web view as well. To use the UniWebView the package needs to be installed in the current project and the file ExampleUWVController.cs needs to be updated by removing the first #define in the file. If no UniWebView is available, and the #define is commented, the rest server can still be accessed via a normal web browser.

Please be aware of the code in the ExampleUWVController.cs file and its comments when you want to implement something like this in production.

iOS

Android

Mac Only - Webbrowser

mDNS Example

This example uses an external library for the mDNS requests, the library can be any open source library for mDNS requests. The external library is not supported and only an example is provided.

This example shows how rest servers could be discovered using mDNS. This can be used for mobile devices in course settings (for example for VR headsets). The advertisements of mDNS hosts and the discovery is not instant and needs some time to propagate, it is also very network dependent. Which means that the network must support multicast udp packets. Most home networks do support these, but almost all enterprise networks do not (due to security). Another thing to consider is network “breaks”, for example cable network and wireless networks are usually separated and the hardware used needs to be configured and support multicast udp packets.

If you want to use this in production, please consider the above points and test it thoroughly. For example, if used in a training setup with VR headsets, it may be a good option to bring your own custom network hardware to be safe.

Itch.IO Login Example Since 1.13.0

This example shows how an application could log in via itch.io OAuth variant to allow API access. This could be used to enable DLC or purchase proofs among other use cases.

See the video on how to setup and use the example.

OAuth Client Example Since 1.13.0

This shows an implementation for the OAuth Auth Code Flow where the user can log in a remote application for additional features or to access a remote API (Twitch, Patreon and others). This example implementation is shown with the open source Keycloak server. Any other OAuth Auth Code compatible server could be used.

See the video on how to setup and use the example.