(1.2.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.