Skip to main content

Getting Started: Sending Commands

The API used to communication with Spectre Dimensioners on the same network uses HTTP REST/SOAP. It is not encrypted, and should only be used in local networks if message privacy is important. The default port used is 7100, although it is configurable in the config.xml. Requests are made as either a POST or GET request to the server’s IP address on the specified port. The server responds with either XML or binary data in the case of a file request.

Formatting a Single Command​

A majority of API commands can be issued as either GET or POST requests. If a particular request type is unavailable for the command, it will not be shown.

Below is a sample of how each request looks based on content type (JSON or XML), and request type (POST or GET).

Request​

Endpoint​

Cargo Spectre GET requests do not expect a body. A sample request looks like:

GET http://10.1.1.2:7100/ApiName

ApiName can be either capitalized or lower case. For instance, this is an equally valid GET request:

GET http://10.1.1.2:7100/apiname
Capital Api Names

Although ApiNames can be lowercased, capital is recommended because Parameters cannot be capitalized.

Desired response format:

Accept: application/xml (DEFAULT)

Response​

Responses are returned in either XML or JSON depending on the accept header provided.

Small changes to outputs may occur

Cargo Spectre reserves the right to append additional nodes to the paths. Cargo Spectre will not remove or rearrange paths (e.g. /Responses/Dimension/Info/Dimensions/ will not disappear, nor will it become /Responses/Dimension/Output/Dimensions/) but some paths may be 'tacked on' (e.g. /Responses/Dimension/Info/AdditionalData/)

Such 'tacking on' may result in your code receiving unexpectedly longer outputs; if you are searching for keywords on specific line-numbers, your code may break.

Use a JSON/XML parser with the full path to make your code as resilient as possible.

Node names not guaranteed to be unique, but full paths are

Cargo Spectre highly recommends parsing the full XML or JSON tree instead of looking for a setting at a specific line number or by a specific keyword. Cargo Spectre promises that paths will be unique, but specific node names may not. E.g. 'Dimension' might be repeated, but /Responses/Dimension/Output/Dimensions/ will not.

Use a JSON/XML parser with the full path to make your code as resilient as possible.

<Responses>
  <ApiName1 code="0">
    <ApiOutputTree/>
  </ApiName1>
</Responses>

Or, for simple requests:

<Responses>
  <ApiName1 code="0"/>
</Responses>

Example: <Ping> a Machine​

The Ping command is useful on app startup to ensure that a machine is still active. It can also be used to check machine state intermittently throught operation.

Request​

Request a ping from a machine with local IP address 10.1.1.2 set to port 7100 to check that the machine is active.

Endpoint​

GET http://10.1.1.2:7100/Ping

Header​

Desired response format:

Accept: application/xml (DEFAULT)

Response​

Ping, like all Dimensioner APIs, returns a status code of 0 if the command executed successfully. Checking for code 0 before continuing ensures successful operation of your integrated app.
<Responses>
  <Ping code="0"/>
</Responses>

Sending Multiple Commands in a Request​

Multiple commands can be sent in one request with either request type. Cargo Spectre expects all API commands to be sent within a single Requests tag

Endpoint​

A sample request for ApiName1 and ApiName2 is concatenated with a + between the two commands.

GET http://10.1.1.2:7100/ApiName1+ApiName2

Or GET http://10.1.1.2:7100/apiname1+apiname2

Capital ApiNames

Although ApiNames can be lower case, it is recommended to capitalize them to avoid confusion given that parameters are currently case-sensitive.

Header​

Desired response format:

Accept: application/xml (DEFAULT)

Sending Parameters in Requests​

Commands can accept certain parameters.

Endpoint​

The request for two API commands is modified below for the instance where two commands can accept certain parameters; in this case, the sample inputs Value and Return.

However, as an unfortunate exception to the capitalization rule above, the parameter name must be capitalized.

GET http://10.1.1.2:7100/ApiName1?Value=somevalue+ApiName2+ApiName3?Return=yes

Or

GET http://10.1.1.2:7100/apiname1?Value=somevalue+apiname2+apiname3?Return=yes

For this reason, it is recommended to simply use capital first letters for API names to avoid confusion.

Header​

Desired response format:

Accept: application/xml (DEFAULT)

Requesting Multiple Parameters Per Command​

Some commands can accept multiple parameters.

Endpoint​

The & operator is used to indicate to the machine the presence of a second parameter. The below request sends a command with no parameters, then one parameter, then two.

info

In the example below, the ApiName3 command receives two parameters called Param and SecondParam, as in:

ApiName3?Param=value&SecondParam=value.


GET http://10.1.1.2:7100/ApiName1+ApiName2?Value=somevalue+ApiName3?Param=something&SecondParam=yes

Header​

Desired response format:

Accept: application/xml (DEFAULT)

Escaped Values in GET Requests​

Certain values need to be encoded in GET requests to be properly parsed.

Similar to how some code requires one to escape special characters with backslashes, e.g. \" instead of simply a ", Cargo Spectre requires users of GET requests to escape certain characters with a delimiter. This delimiter signifies that the next characters after it should be converted into a special character instead of parsed as a basic string or as an API command.

The %5C delimiter is used to specify that. You might recognize it as the URL-safe encoding for a backslash.

Examples​

For instance, if a SetSetting API command is used to set the name of a machine to Test Machine, the following will not work:

GET http://10.1.1.2:7100/SetSetting?Path=/Setting/Device/Name&Value=Test Machine.

Similarly, simply setting the HTTP-appropriate encoding of the space character will not work as Cargo Spectre reserves %20 to delimit commands in the Proxy API.

GET http://10.1.1.2:7100/SetSetting?Path=/Setting/Device/Name&Value=Test%20Machine

Only escaping the URL-safe encoding of the space character will cause it to be properly parsed. This is because Cargo Spectre reserves the URL-safe encoding of the backslash as a way to escape such characters.

GET http://10.1.1.2:7100/SetSetting?Path=/Setting/Device/Name&Value=Test%5C%20Machine

Table of All Special Characters​

All of the characters in the right column must be written as %5C___ in order to be properly read.

Example: A "+" is represented as %5C%2B.

Encoded CharacterCharacter
%20space
%5C\
%2B+
%25%
%26&
%3D=