(1.3.0) API Introduction

The ICE API is an API built on a URI messaging system used to execute commands in ICE. It exposes functionalities such as Layer, Workspace and Session management.

Connecting

To connect to the ICE API, you will need to establish a local UDP or TCP connection with the ICE server. The server address and port are configurable and should be provided by your system administrator.

Before you can start sending URI messages to execute commands in ICE, you need to connect to the server and authenticate by sending a "apikey" URI message. This message should include your API key as a query parameter. The API key is a unique identifier that will be provided to you.

apikey?value=x

In this example, "x" represents your API key.

Sending a URI Message

In the ICE API, URI (Uniform Request Identifier) messages are used to execute commands and interact with the system. These messages are divided into two main components: the path and the queries.

1. Path: The path component of a URI message represents the command or action you want to perform in ICE. It is divided by forward slashes (/) and provides a hierarchical structure to organize the functionality. The path can include properties that have both "get" and "set" messages, as well as action messages that have neither "get" nor "set" functionality.

2. Queries: The queries component of a URI message provides additional parameters or information related to the command or action being executed. Queries start with a question mark (?) and consist of key-value pairs, separated by plus signs (+). The queries allow you to specify specific values or options for the command you are sending.

For example, let's consider the following URI message:

layer/geometry/scale/set?id=x+value=n

In this example:

• The path is "layer/geometry/scale/set."

• The queries are "id=x" and "value=n."

This URI message is instructing ICE to set the scale of the Layer. The "id" query specifies the identifier of the layer, and the "value" query specifies the desired scale (in this case, n).

Types of Message

In the ICE API, there are different types of messages that can be used to control properties and perform actions. These message types include Get, Set, Subscribe, and Action.

1. Get:
   The Get message is used to retrieve the current value of a property in ICE. It allows you to query the system and receive information about a specific property. The URI message for a Get operation typically includes the property path and any necessary query parameters. For example:

   layer/geometry/scale/get?id=x+value=n

   The above message requests the current value of the scale property for the geometry layer, with the identifier "x" and value "n".

2. Set:
   The Set message is used to update or modify the value of a property in ICE. It allows you to set a new value for a specific property. The URI message for a Set operation includes the property path and the new value as query parameters. For example:

   layer/geometry/scale/set?id=x+value=n

   The above message sets the scale property for the geometry layer to the new value "n", with the identifier "x".

3. Subscribe:
   The Subscribe message is used to receive notifications whenever the value of a property changes in ICE. By subscribing to a property, you can get updates whenever there is a change, allowing you to stay informed. The URI message for a Subscribe operation typically includes the property path and the identifier for the property you want to subscribe to. For example:

   layer/geometry/scale/subscribe?id=x

   The above message subscribes to the scale property of the geometry layer with the identifier "x". Once subscribed, the system will send a message back to the client whenever the value of the property changes.

4. Action:
   The Action message is used to perform a specific action or command in ICE that doesn't involve getting or setting a property. Action messages are typically used for operations like removing a layer, triggering an event, or executing a specific action within the system. For example:

   The above message triggers the action to remove the layer with the identifier "x".

It's important to refer to the API documentation to determine the appropriate message type and construct the URI messages accordingly.

OSC (Open Sound Control)

Sending OSC (Open Sound Control) messages to the ICE API can be accomplished using three distinct formats: address-only, paired arguments, or a single argument. This flexibility allows for different methods of constructing messages depending on the specific needs of the application or the developer's preference.

Sending OSC Messages using Address Only

This method is recommended. It involves embedding the entire URI message, including keys and their corresponding values, directly within the OSC address.

Format Details:

• OSC Address: The OSC address in this format should include the complete URI, integrating both the key (identifier) and its value. This approach removes the need for additional arguments, as the entire command or setting is encapsulated within the URI.

Example of Modified OSC Message Approach:

• OSC Address for Setting Position: layer/geometry/position/set?id=1246759239+x=0.5+y=0.5

  In this example, the OSC message is designed to set the x and y positions of a layer with the identifier 1246759239. The values for the x and y coordinates (0.5 and 0.5 respectively) are directly included in the OSC address.

• OSC Address for Setting Scale: layer/geometry/scale/set?id=1246759239+scale=0.8

  Here, the message is setting the scale of a layer identified by 1246759239 to 0.8. The scale value is directly appended to the OSC address.

Sending OSC Messages as Paired Arguments

In the paired arguments format, each OSC message is composed of pairs of arguments, with each pair representing a key and its corresponding value.

Format:

• Arg [0] - Key (Identifier)

• Arg [1] - Value

Example:

• Address: layer/geometry/position/set

• Arg [0]: “id”

• Arg [1]: 1246759239

• Arg [2]: “x”

• Arg [3]: 0.5 (value for x)

• Arg [4]: “y”

• Arg [5]: 0.5 (value for y)

In this example, the OSC message is setting the x and y positions of a layer with the identifier 1246759239. The first pair, "x" and 0.5, sets the x-coordinate, and the second pair, "y" and 0.5, sets the y-coordinate.

The resulting URI message would be

layer/geometry/position/set?id=1246759239+x=0.5+y=0.5

Sending OSC Messages with a Single Argument

In specific situations, the OSC protocol within the ICE API allows for single-argument messages. This approach is useful when the need arises to transmit a straightforward command that involves just one specific parameter.

Format Details:

• OSC Address: The OSC address in this format must end with an equals sign (=), indicating that it is ready to accept a single argument directly appended to it.

• Arg [0]: This is the sole argument in the message. It does not explicitly separate the key and value but implicitly contains the value that needs to be set.

Example of Single-Argument OSC Message:

• OSC Address: layer/geometry/scale/set?id=1246759239=

• Arg [0]: "0.8"