Frequently Asked Questions

Port considerations when distributing the rest server

  • Ports on each system are limited to 65.536 ports
  • Ports unused on the developer machine may be used on a client machine
  • Applications might need white listing to be allowed to open ports (anti-virus, firewalls, etc.)
  • Users might need to set a port themselves
  • Ports can’t be opened and closed at random, they have a state and are managed by the system. Closing does take time.
  • Each operating system has other default and behaviour when handling opening and closing of ports

SocketException - Only one usage of each socket is normally permitted

All socket exceptions are thrown from the underlying runtime and represent messages from the operating system. When operating with the network, the rest server is calling the operating system to open a port and SocketExceptions are the answer from the operating system when something goes wrong.

In the case of duplicate usage there are multiple error sources:

  • Multiple rest server objects in the scene that are using the same port
  • Other processes on the system that are using this port
  • Ports that are not accessible to the process (ex: on linux ports below 1024 are for the root user)
  • Virus scanners, personal firewalls, endpoint security and/or other software prohibiting the access quietly

Every operating system has ways to find out which port is used by which software, for example with netstat. For Windows there is also a GUI tool like this. From the rest server there is no workaround for these problems, and they must be mitigated by the developer.

Compilation Errors after import

The plugin needs the .NET compatibility set to newer C# versions. Usually when you get compilation errors, the “API Compatibility Level” is set to “.NET Standard 2.0”. Please set it to “.NET 4.x” or newer.

If you still encounter problems, please feel free to contact me.

I can’t find the visual scripting nodes

Please make sure that you fulfill these requirements:

  • Unity 2021 LTS or higher
  • Visual Scripting package 1.7 or higher imported in the project
  • Rest Server Package 1.4.0 or higher imported in the project

If the Rest Server nodes are still not showing up, please regenerate Visual scripting nodes:

  • Go to Edit > Project settings
  • Select Visual Scripting on the left side
  • Click on “Regenerate Nodes” and wait until the process is finished

The rest server nodes should now be accessible. If you still encounter problems, please feel free to contact me.

How to access the server from other machines

The make the server available make the rest server listen on all IPv4 interfaces. After you enter playmode and start the server, all listening ips are displayed

My endpoint is not called/doesn’t work

When calling the endpoint,

  • the server responds with “404 Not Found”:
    • Check the Rest Server inspector if the calling URL is listed
    • Validate that the GameObjects and Component is enabled, that registers the endpoint
    • Enable “Access log” and “Debug log” in the Rest Server inspector. Restart the Rest server and check the unity console log for warnings and errors
  • the server responds with “500 Internal Server Error”:
    • The endpoint, or the Rest server, encountered an error. Check unity console log for warnings and errors
  • the server doesn’t respond at all:
    • Double-check the browser url with IP and Port the Rest Server Inspector reports
    • Ensure that Unity is in Play Mode
    • Ensure that the Rest Server is started and enabled
    • Ensure that the Rest Server Game Object is enabled
    • Validate that “Project Settings -> Player -> Choose the current Platform -> Resolution and Presentation -> Run in Background” is enabled
    • Enable “Access log” and “Debug log” in the Rest Server inspector. Restart the Rest server and check the unity console log for warnings and errors

Registering the same endpoint path multiple times

It is technically possible to register the same endpoint path multiple times. Which endpoint implementation will be executed is undefined. The rest server will issue a warning when a duplicate endpoint is registered.

There are cases where duplicates can not be identified beforehand. This is the case when using endpoints with Regex definitions. Make sure that the Regex definitions do not overlap to have a stable endpoint resolution on each call.

How can I upload binary files (images, etc.) to the rest server

The rest server main focus is handling REST interfaces which consist of JSON, XML or similar formats. The underlying library provides methods to access the binary data of the request itself and the rest server exposes this (for example the BodyBytes property on the RestRequest class). The HTTP standard itself defines multiple and various methods on how to transmit binary data, which may need custom parsing.

If there is the need to handle binary data, there are few ways to accomplish this, which are described in the next sections

Base64 Upload

The binary data can be base64 encoded by the client and sent to the server. Either the body is completely base64 encoded or the base64 encoded binary data is included in a json structure. On the server side C# methods can be used to convert base64 back to binary, like this

var data = Convert.FromBase64String(request.Body)

Raw Upload

In this variant the request body is the uploaded file directly/raw. This can easily be achieved when the client is a JavaScript application and/or a custom application where the request can be controlled completely. The binary body data can be accessed in the request via this method

var data = request.BodyBytes


Multipart/form-data is the default HTML upload method when using forms in browsers. It is also the most complicated as multiple files can be uploaded with the same request and the body follows a complicated structure. It is outside the scope of the rest server library to provide a full parser for this as there are already advanced open source libraries that do this.

Nevertheless, the rest server includes a very simple parser to parse very simple multipart/form-data requests. See the Static Content Example.

List<MultiFormDataElement> uploadData;
try {
    uploadData = new SimpleMFDParser().Parse(request);
catch (SystemException e) {
    request.CreateResponse().InternalServerError("No form data found.").SendAsync(); 

var data = uploadData[0].Data;

Third party application

This alternative variant doesn’t upload files directly, but uses a third party service to upload files to the rest server. This might be a good solution if the data to upload is very large.

A third party service is used and the client uploads the files to the third party service. Upon completion the client informs the server that the file has been uploaded and under which url the file can be downloaded. The server continues to download the file from the third party service. With this method no upload to the rest server is done directly.

Examples could be AWS S3 buckets, AWS S3 pre-signed uploads and others.