Viz Arc User Guide
Version 2.0 | Published July 03, 2024 ©
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:
Error rendering macro 'toc'
[com.ctc.wstx.exc.WstxLazyException] com.ctc.wstx.exc.WstxUnexpectedCharException: Unexpected character '=' (code 61) (expected a name start character) at [row,col {unknown-source}]: [17,366]
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.
[ { "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.
{ "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 is updated.
{ "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:
200 OKExecuter
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.
200 OKProjects
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.
[ { "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/{id}
Returns the project with the specified id, if it exists. If two projects with the same name exist in the GH and the local disk, the one of the local disk will be returned first.
{ "name": "gh:Animations", "lastModified": "2023-05-09T13:53:32.4633996+00:00", "location": 1, "profileIndex": 0, "tabs": []}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.
[ { "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.
{ "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.
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.
With the magnifier icon, you can filter the actions by name.
