.. _rest-server:

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 :ref:`connect multiple instances <gaiasky-master-slave>` and to enable :ref:`the multi-projector setup in planetariums <planetarium-multi-projector>`.

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

.. contents::
  :backlinks: none

In order to enable the REST server to expose the Gaia Sky API (:ref:`v1 <apiv1>` and :ref:`v2 <apiv2>`) over HTTP, you need to modify the :ref:`configuration file <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:

.. code:: yaml
    
    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`` -- :ref:`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`` -- :ref:`APIv1 <apiv1>`, contains a list of all the APIv1 methods.

.. figure:: img/screenshots/firefox-rest.jpg
   :alt: Help page with REST calls
   :align: center
   :target: ../_images/firefox-rest.jpg

   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 :ref:`APIv1 <apiv1>` and :ref:`APIv2 <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 :ref:`scripting API documentation <scripting>`, and more precisely, the :ref:`APIv2 documentation <apiv2>`, 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:

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

You can clear it with:

.. code:: bash
    
    curl "http://localhost:$PORT/api/clearHeadlineMessage"