Documentation Center

Viz Arc User Guide

Version 1.9 | Published October 31, 2023 ©

REST Web API

Viz Arc Rest Service provides a Web API that allows you to , trigger specific actions or control the Playlist.

The samples below assume that you have installed Viz Arc REST Service and that it's running on localhost and the REST Web API is configured to run on port 9004. The REST Web API port can be configured in the General Settings, under the Communication section.

A Swagger webapp that describes every API can be found at http://localhost:9004/swagger/.

This section contains the following examples:

Info: The samples below use curl command line tools to demonstrate usage and python to beautify the returned JSON output. Note that these tools are not required for the Web API to function correctly.

DataMap

You can set, read and delete DataMap variables through the Web API.

GET /api/v1/DataMap

Gets the list of all the key-value pairs.

curl -s -X GET http://localhost:9004/api/v1/DataMap | python -m json.tool
[
{
"key": "Hello",
"value": "World!"
},
{
"key": "WhiteListIPRanges",
"value": "0.0.0.0/0"
}
]

GET /api/v1/DataMap/{key}

Gets the key-value pair identified by the specified key.

curl -s -X GET http://localhost:9004/api/v1/DataMap/key | python -m json.tool
{
"key": "Hello",
"value": "World!"
}

POST /api/v1/DataMap

Adds a new key-value pair or an array of them to the DataMap. The payload must be sent as JSON body. If the key already exists the value will be updated.

curl -s -H 'Content-Type: application/json' -d "{ 'Key': 'Hello', 'Value': 'World!' }" -X POST http://localhost:9004/api/v1/DataMap
{
"Key": "key",
"Value": "hello"
}

DELETE /api/v1/DataMap/{key}

Delete a key/value pair by sending a DELETE message, for example to delete "key2" use:

curl -s -X DELETE http://localhost:9004/api/v1/DataMap/key2 | python -m json.tool
200 OK

Executer

The Executer endpoints allows you to execute a specific action either by using its name or its ID.

POST api/v1/Executer

Executes the selected action. In order to identify a specific action, the user must specify the actionId, the projectId, the profileId and the executionType.

curl -s -H 'Content-Type: application/json' -d "{ 'actionId': 'a45dbfda-d197-49ff-9995-66d3c319e1fc', 'projectId': 'gh:Sunday_Elections', 'profileId': 'Profile-1', 'executionType': 'EXECUTE' }" -X POST http://localhost:9004/api/v1/Executer
200 OK

Projects

The Projects endpoint allows you to get a list of all available projects and to load a project.

Info: Viz Arc can store and read projects from two different locations: the Graphic Hub or the local file system. In order to distinguish the source of the project, the project's name is prefixed by the keywords "gh:" or "local:" (e.g. "gh:sunday_elections" or "local:sunday_elections").

Likewise, the "location" property in the responses, indicates whether the project resides on Graphic Hub (value "1") or on the file system (value "0").

GET api/v1/projects

Returns a list of all available Projects, first the projects located on the Graphic Hub, then the ones on the file system.

curl -s -X GET http://localhost:5004/api/v1/Projects | python -m json.tool
[
{
"name": "gh:Animations",
"lastModified": "2023-05-09T13:53:32.4633996+00:00",
"location": 1,
"profileIndex": 0,
"tabs": []
},
{
"name": "local:Skating",
"lastModified": "2023-05-11T07:53:51.80198+00:00",
"location": 0,
"profileIndex": 0,
"tabs": []
}
]

In the example above, two projects were found.

The name of the project is prefixed by the keywords "gh:" or "local:"; this prefix indicates whether the project is stored in the Graphic Hub or on the file system.

GET api/v1/projects/current

Gets the name and location (Local or GraphicHub) of the currently loaded project.

curl -s -X GET http://localhost:5004/api/v1/projects/current | python -m json.tool
{
"name": "local:Skating",
"lastModified": "2023-05-11T07:53:51.80198+00:00",
"location": 0,
"profileIndex": 2,
"tabs": [
{
"name": "show",
"index": 0,
"isEditorOnly": false,
"actions": [
{
"uuid": "ff1ae771-4c69-42e4-ba8a-ad98747a5477",
"name": "Logo",
"type": "Template",
"actionType": "TEMPLATE",
"engineType": "VIZ",
...

Profiles

The Profiles endpoint allows you to retrieve information about the available Profiles, Channels and Engines.

GET /api/v1/profiles

Returns the entire list of profiles available in Viz Arc.

curl -s -X GET http://localhost:5004/api/v1/profiles | python -m json.tool
[
{
"name": "Local",
"channels": [
{
"name": "Local",
"type": 1,
"engines": [
{
"name": "localhost"
}
],
"model": {
"engineConfigTuple": [
{
"item1": {
"name": "localhost",
"ipAddress": "127.0.0.1",
"port": 6100,
"launcherPort": 5644,
"webInterfacePort": 30010,
"webSocketPort": 30020,
...

GET api/v1/profiles/{id | name}

Returns the profile specified by the id or name.

curl -s -X GET http://localhost:5004/api/v1/profiles/0 | python -m json.tool
{
"name": "Local",
"channels": [
{
"name": "Local",
"type": 1,
"engines": [
{
"name": "localhost"
}
],
"model": {
"engineConfigTuple": [
{
"item1": {
"name": "localhost",
"ipAddress": "127.0.0.1",
"port": 6100,
"launcherPort": 5644,
"webInterfacePort": 30010,
"webSocketPort": 30020,
...

Web Application Sample Usage

Once the Viz Arc REST service is installed, it also hosts a Web Application that uses some of the APIs described above.

images/download/attachments/140813552/9004.png

By selecting a Project and a Profile, we can see the Project's structure. By clicking on an action, Viz Arc REST Service executes it.

When clicking the Execute History button, you can see the list of actions in the same order as they were executed.

images/download/thumbnails/140813552/exec.png

With the magnifier icon, you can filter the actions by name.

images/download/thumbnails/140813552/filt.png