.. _ska-tango-images-rest-server:

============================
ska-tango-images-rest-server
============================

This image contains `TangoRestServer
<https://github.com/tango-controls/rest-server>`_.  ``TangoRestServer`` is a web
sever which exposes your Tango control system via a REST API.

Summary
-------

Release |version| of ska-tango-images provides the |rest-server-imgver| tag of
the ska-tango-images-rest-server OCI image.

The image uses :ref:`ska-tango-images-tango-admin` as a base image and so
provides the same features, in addition to the ``TangoRestServer`` application.

If you are publishing works that rely on the ``TangoRestServer`` application, it would be greatly appreciated if you could cite the application using the following DOI:

  `https://zenodo.org/records/14967079 <https://zenodo.org/records/14967079>`_

Included Software
*****************

.. list-table::
   :header-rows: 1

   * - Package
     - Version
   * - TangoRestServer
     - |tsd-rest-version|
   * - tango_admin
     - |tangoadmin-version|
   * - cppTango
     - |cpptango-version|
   * - ZeroMQ
     - |zeromq-version|
   * - omniORB
     - |omniorb-version|
   * - opentelemetry-cpp
     - |otel-version|

Usage Example
-------------

To launch the "rest" instance of the TangoRestServer device server, connecting to
``TANGO_HOST=localhost:10000`` run the following:

.. code-block:: bash
   :substitutions:

   docker run --rm --env TANGO_HOST=localhost:10000 --net=host \
     --detach --name rest-server \
     |oci-registry|/ska-tango-images-rest-server:|rest-server-imgver| \
     rest

This will launch a REST server listening on port 10001, to check that this is
working run the following curl command:

.. code-block:: bash

    URL="http://localhost:10001/tango/rest/rc4/hosts/localhost/10000/devices/sys/rest/0"
    curl -s -u "tango-cs:tango" $URL | python -m json.tool

Which should output something like the following:

.. code-block::

  {
      "name": "sys/rest/0",
      "info": {
          "last_exported": "4th February 2025 at 15:42:10",
          "last_unexported": "?",
          "name": "sys/rest/0",
          "ior": <some very long IOR>,
          "version": "5",
          "exported": true,
          "pid": 7,
          "server": "TangoRestServer/rest",
          "hostname": "localhost",
          "classname": "unknown",
          "is_taco": false
      },
      "attributes": "http://localhost:10001/tango/rest/rc4/hosts/localhost/10000/devices/sys/rest/0/attributes",
      "commands": "http://localhost:10001/tango/rest/rc4/hosts/localhost/10000/devices/sys/rest/0/commands",
      "pipes": "http://localhost:10001/tango/rest/rc4/hosts/localhost/10000/devices/sys/rest/0/pipes",
      "properties": "http://localhost:10001/tango/rest/rc4/hosts/localhost/10000/devices/sys/rest/0/properties",
      "state": "http://localhost:10001/tango/rest/rc4/hosts/localhost/10000/devices/sys/rest/0/state",
      "_links": {
          "_self": "http://localhost:10001/tango/rest/rc4/hosts/localhost/10000/devices/sys/rest/0",
          "_parent": "http://localhost:10001/tango/rest/rc4/hosts/localhost/10000/devices/"
      }
  }


The REST server can be stopped with:

.. code-block:: bash

     docker stop rest-server