Using the Rose API

The WebAgent includes a Rose server for StreamLab which supports a simple API.

Note: Wherever is included in the URL, this represents the rose username. At the moment only one user is supported (called user).

Supported options include:

Routes Op Returns
/_help Get HTML – help for the rose api
/_project/<user>/<project> Get JSON project definition (The rose file, not the slab file, so excludes all dashboards)
/_projects/<user> Get JSON array of project elements for the user
/_project_script/<user>/<projec\t> Get SQL - entire project script for the user
/_project_start/<user>/<project> Get SQL – script to start project pumps
/_project_stop/<user>/<project> Get SQL – script to stop project pumps
/_project_removal/<user>/<project> Get SQL – script to drop project
/_download/<user>/<project> Get JSON – the project slab file Must run /_project_export first
/_project_export/<user>/<project> Get JSON containing the _download URL Must be run before /_download
/_project_dashboards/<user>/<project name> Get Returns a shell script with embedded dashboards:
  • Pipe this into bash to get them separated
  • Dashboards need to have been actually materialized in StreamLab (by viewing them)
  • Dashboards need to have been saved
  • The StreamLab project must have been saved after the dashboard is saved
/_project_export_delete/<user>/<project> Get Deletes the slab file that is created on the rose server by /_project_export
/_project_rename/<user>/<project>/<newname> Get Renames the project; does NOT change the project schema. Returns ‘false’ (meaning success) or an error message
Entrypoint Type Post document contains
/_project/<user>/<project> Post JSON project to be uploaded
/_project/<user>/<project> Del Delete the project

Examples

To get the project SQL from a project called t which is saved on localhost:

curl -o t.sql http://localhost:5580/_project_script/user/t

To get the dashboards for a project called buses:

curl http://localhost:5580/_project_dashboards/user/buses | bash

Note: You can use wget as an alternative to curl

These APIs can easily be packaged into a script to save SQL, JSON and SLAB files into a suitable location (including into source control)

You do not need to login to the StreamLab server command line, or to have any specific software installed.

You can also automate these scripts.

Provides options for loading project components into a remote StreamLab or s-Server instance (so it is easy for example to build that into a docker or vagrant startup)

Limitations

The WebAgent server has to be up and running for these components to be extracted. To use these with source control, you will either need to export them all from the development environment into source control or:

  • Export and source control only the SLAB file (which includes everything) from developmentcat b
  • At deployment time, run a WebAgent server simply to break down the SLAB file into the components needed for runtime

The dashboard export assumes that the caller is running in a Linux environment. If you are running Windows users, you may be able to use a Cygwin or Linux shell (for example under Windows Subsystem for Linux).

Dashboard Information

When you export dashboards, they have auto-generated names. For example, within StreamLab the dashboard may be given a generated URL such as:

http://localhost:5590/dashboard/user/autogen/dash-2019-11-09T11:18:10.842-f50a0c

When extracted using /_project_dashboards the name is flattened to:

autogen-dash-2019-11-09T11:18:10.842-f50a0c.json

If you want meaningful names to appear in the s-Dashboard menu, you will need to add some kind of file rename mechanism to your extract script.

Dashboard information also includes no reference to the StreamLab project name or pipeline name or the type of dashboard included. That is, the dashboard does not indicate whether it is a "quickie" dashboard generated from a step in a pipeline (the grey icon available in each step) or a dashboard defined as a step in a pipeline (the pink eye icon). In the first case, the existence of the dashboard is indicated by turning the light grey eye icon dark grey. In the second case the icon is turned pale pink when the dashboard is generated, and then a darker pink once the dashboard has been saved.