Receiving Requests

To receive requests you need to install the Rest Server package, create a GameObject and add the RestServer component to it. This is described in the Install. After the installation the rest server is start up default on http://localhost:8080 and can receive requests.

Sub-paths under http://localhost:8080 can now be registered and extended with custom functionality.

Defining/Registering an Endpoint

Endpoint, or urls, that the server shall respond to, can be registered any time before or after the server has been started. Only after an endpoint has been registered, it can be called from a possible client.

An endpoint can be registered like this:

using RestServer;
using UnityEngine;

public class Example : MonoBehaviour {
    // Reference to the RestServer instance 
    public RestServer.RestServer server;
    
    private void Start() {
        // Register the endpoint
        server.EndpointCollection.RegisterEndpoint(HttpMethod.GET, "/position", (request) => {
            // do work
            
            // send information back
            request.CreateResponse().SendAsync();
        });
    }
}

The library provides two methods to register an endpoint:

  • void RegisterEndpoint(HttpMethod, String, Action)
  • void RegisterEndpoint(HttpMethod, Regex, Action)

The first parameter describes to which Http Verb the endpoint should respond to (GET, PUT, POST, …) while the second argument specifies the location of the endpoint. In the first overload, the string case, the endpoint is specified from the server root. So the location "/ping" will be accessible through http://localhost:8080/ping. The second overload, the Regex case, allows to specify a regex the incoming location has to fulfill so to execute the defined Action. The Action is executed, when an incoming request matches both the HttpMethod and the string/Regex. Actions can be specified with the Lambda syntax

server.EndpointCollection.RegisterEndpoint(HttpMethod.GET, "/position", (request) => { 
    // Action
    request.CreateResponse().SendAsync();
});

or with a method reference

void Start()
{
    server.EndpointCollection.RegisterEndpoint(HttpMethod.GET, "/position", Handler);
}

private void Handler(RestRequest request) {
    // Action
    request.CreateResponse().SendAsync();
}

Regular expression endpoints

  • void RegisterEndpoint(HttpMethod, Regex, Action)

Regular expressions can be used to match more complex patterns. A good practice is to make sure, that regular expressions match the complete path. To do this, start the regular expression with ^ and end it with $. This will make sure, that the regular expression matches the complete path and not only a part of it.

Note that regular expression endpoints can overlap and partial match endpoint paths depending on how the endpoint is defined.

Path Parameters Since 1.10.0

  • void RegisterEndpoint(HttpMethod, String, Action)

Endpoints can be registered with path parameters, that allow parts of the url to be dynamic and extracted from the endpoint handler. Path parameters are defined by a { and } around the parameter name. The parameter name can be any string, but must be unique in the endpoint path. The parameter name can be used to access the parameter value in the endpoint handler.

server.EndpointCollection.RegisterEndpoint(HttpMethod.GET, "/position/{id}", (request) => {
    var id = request.PathParams["name"].ValueString;
    // do work
    request.CreateResponse().Body(id).SendAsync();
});