REST Server

Gaia Sky provides a REST server feature that exposes the scripting API over the network via an HTTP server. This feature is used to connect multiple instances and to enable the multi-projector setup in planetariums.

Hint

The REST feature may permit remote code execution and open your machine to vulnerabilities. Only use the feature in a trusted environment!

In order to enable the REST server to expose the Gaia Sky API (v1 and v2) over HTTP, you need to modify the configuration file. The default location is ~/.config/gaiasky/config.yaml in Linux and [User.Home]\.gaiasky\config.yaml in Windows and macOS. In that file, there is a property program::net::restPort (double colons indicate nesting) with the default value of -1. You can enable the REST server by setting this value to a positive integer number which will be the listening port of the server. For instance, we can start Gaia Sky with the REST server listening to the port 34487 with:

program:
    net:
        restPort: 34487

Then, start Gaia Sky normally. You should see a couple of lines in the logs starting with RESTServer informing you that the REST server is ready. Then, open your browser and point it to:

  • http://localhost:34487/apiv2 – APIv2, contains a list of all the modules. In general, use http://localhost:34487/apiv2/$MODULE to access the module $MODULE. Here is an exhaustive list:

    • http://localhost:34487/apiv2/base – APIv2 methods in the base module.

    • http://localhost:34487/apiv2/time – APIv2 methods in the time module.

    • http://localhost:34487/apiv2/camera – APIv2 methods in the camera module.

    • http://localhost:34487/apiv2/camera/interactive – APIv2 methods in the interactive camera module.

    • http://localhost:34487/apiv2/scene – APIv2 methods in the scene module.

    • http://localhost:34487/apiv2/data – APIv2 methods in the data module.

    • http://localhost:34487/apiv2/graphics – APIv2 methods in the graphics module.

    • http://localhost:34487/apiv2/camcorder – APIv2 methods in the camcorder module.

    • http://localhost:34487/apiv2/ui – APIv2 methods in the UI module.

    • http://localhost:34487/apiv2/input – APIv2 methods in the input module.

    • http://localhost:34487/apiv2/ouptut – APIv2 methods in the output module.

    • http://localhost:34487/apiv2/refsys – APIv2 methods in the refsys module.

    • http://localhost:34487/apiv2/geom – APIv2 methods in the geometry module.

    • http://localhost:34487/apiv2/instances – APIv2 methods in the instances module.

  • http://localhost:34487/api – APIv1, contains a list of all the APIv1 methods.

Help page with REST calls

The help page showing all REST server API calls in Firefox

Using the REST server

The API allows for developing additional software that interfaces with Gaia Sky without the need for language-specific bindings or inter-process communication protocols. Calling methods from the Gaia Sky APIv1 and APIv2 is enabled locally and remotely via HTTP.

The syntax of API commands is set to be close to the Java method interface, but does not cover it in all generality to permit simple usage. Particularly note that the REST server receives strings from the client and will try to convert them into correct types.

Commands require HTTP request parameters having the names for the formal parameters of the script interface methods to allow simple construction of HTTP requests based on the scripting interface source documentation. We use Java reflections with access to the formal parameter names.

Both GET and POST requests are accepted. Although GET requests are not supposed to have side effects, we include them for easy usage with a browser.

Assuming the REST server listens to the port $PORT, issue commands with a syntax like the following:

  • http://localhost:$PORT/apiv2/camera/get_position

  • http://localhost:$PORT/apiv2/time/start_clock

  • http://localhost:$PORT/apiv2/base/internal_to_km?internalUnits=12.33

  • http://localhost:$PORT/api/setCameraUp?up=[1.,0.,0.]

  • http://localhost:$PORT/api/getScreenWidth

  • http://localhost:$PORT/api/goToObject?name=Jupiter&angle=32.9&focusWait=2

Give booleans, integers, floats, doubles, strings as they are, vectors are comma-separated with square brackets around: true, 42, 3.1, 3.14877, Super-string, [1,2,3], [Do,what,they,told,ya]. Note that you might need to escape or URL-encode characters in a browser for this (e.g. spaces or “=”).

Response with return data is in JSON format, containing key/value pairs. The "success" pair tells you about success/failure of the call, the "value" pair gives the return value. Void methods will contain a "null" return value. The "text" pair can give additional information on the call.

The "cmd_syntax" entry you get from the help command (e.g. http://localhost:$PORT/apiv2/$MODULE/help and http://localhost:$PORT/api/help) gives a summary of permitted commands and their return type. Details on the meaning of the command and its parameters need to be found from the scripting API documentation, and more precisely, the APIv2 documentation, and the APIv1 documentation <apiv1>.

Debug

To examine, what happens during an API call, set the default log level of SimpleLogger to ‘info’ or lower (in the build file core/build.gradle).

Return values are given as JSON objects that contain key-value pairs:

  • "success" indicates whether the API call was executed successfully or not

  • "text" may give additional text information

  • "value" contains the return value or null if there is no return value

For testing with curl, a call like the following allows will deal with URL-encoding. The line below, when issued with a running Gaia Sky instance with the REST API server enabled listening to port $PORT, will print the message “Hi, how are you?” in the Gaia Sky window:

curl "http://localhost:$PORT/api/setHeadlineMessage" --data headline='Hi, how are you?'

You can clear it with:

curl "http://localhost:$PORT/api/clearHeadlineMessage"