REST data interface - Variables

Note: We reserve the right to make changes and additions in further versions that might lead to incompatibilities. Therefore it is highly recommended to call this REST data interface out of your application explicitly with the version used during development, not with the latest key.

Read Variable(s)

Reads the current value(s) of the specified variable(s) in the same order as originally supplied. The resulting response being the variable value(s).

Case #1): GET

Request

This is done via the following HTTP GET command:

GET https://%plcaddress%

Description:

%OptionalSessionID% Optionally assigned identifier for the current session (see Create_a_session) to implicitly avoid a session timeout or "" if that is unavailable

%OptionalVariablePathPrefix%

Optionally desired path prefix for each of the variables (e.g. Arp.Plc.Eclr/)

%VariablePath1%

The relative or full path of the first variable (e.g. Go, Arp.Plc.Eclr/Go respectively) as well as an optional index, indices, and/or range of indices in the case of an array variable (e.g. PartArray[2], PartArray[2, 4], PartArray[2, 4, 6-8] respectively)

%VariablePathN%

Relative or full path of the last variable (e.g. CycleCount, Arp.Plc.Eclr/CycleCount respectively) as well as an optional index, indices, -and/or- range of indices in the case of an array variable (e.g. ProductArray[2], ProductArray[2, 4], ProductArray[2, 4, 6-8] respectively).

Response

The response is HTTP status code 200 (OK) for a successful variable read along with the resulting JSON data being the following:

{
  "apiVersion": "%ApiVersion%",
  "variables":
  [
    {
    "path": "%VariablePath1%",
    "value": %VariableValue1%
    },
    …
    {
    "path": "%VariablePathN%",
    "value": %VariableValueN%
    }
  ]
}

Description:

%ApiVersion% Version number of this API (e.g. v1.0)
%VariablePath1% Full path (i.e. path prefix + relative path) of the first variable (e.g. Arp.Plc.Eclr/Go, Arp.Plc.Eclr/PartArray)

%VariableValue1%

Current value of the first variable (e.g. true) or the specified elements of the first array variable (e.g. 200, [200, 400], [200, 400, 600, 700, 800])

%VariableRelativePathN%

Full path (i.e. path prefix + relative path) of the last variable (e.g. Arp.Plc.Eclr/CycleCount, Arp.Plc.Eclr/ProductArray)

%VariableValueN%

Current value of the last variable (e.g. 100) or the specified elements of the last array variable (e.g. 250, [250, 450], [250, 450, 650, 750, 850])

Otherwise, the appropriate HTTP status code (e.g. 400 = Bad Request, 408 = Request Timeout, 500 = Internal Server Error) is reported for a failed variable read.

Hide exampleClick to see an example

Example Request:

GET https://plc/_pxc_api/api/variables?pathPrefix=Arp.Plc.Eclr/&paths=SineWave3,SineWave

 

Example response with status code 200:

{
  "apiVersion": "1.1.0.3",
  "projectCRC": 2373751656,
  "userAuthenticationRequired": true,
  "variables": [
    {
    "path": "Arp.Plc.Eclr/SineWave3",
    "value": -0.910105
    },
    {
    "path": "Arp.Plc.Eclr/SineWave",
    "value": -0.61786
    }
  ]
}

Case #2): POST

Request

Due to potential limits with GET query string, this is alternatively done via the following HTTP POST command:

POST https://%plcaddress%

With the accompanying plain-text data being the following:

sessionID=%OptionalSessionID%&pathPrefix=%OptionalVariablePathPrefix%&paths=%VariablePath1%,...,%VariablePathN%

Description:

%OptionalSessionID% Optionally assigned identifier for the current session (see Create_a_session) to implicitly avoid a session timeout or "" if that is unavailable
%OptionalVariablePathPrefix% Optionally desired path prefix for each of the variables (e.g. Arp.Plc.Eclr/)
%VariablePath1% Relative or full path of the first variable (e.g. Go, Arp.Plc.Eclr/Go respectively) as well as an optional index, indices, and/or range of indices in the case of an array variable (e.g. PartArray[2], PartArray[2, 4], PartArray[2, 4, 6-8] respectively)
%VariablePathN% Relative or full path of the last variable (e.g. CycleCount, Arp.Plc.Eclr/CycleCount respectively) as well as an optional index, indices, and/or range of indices in the case of an array variable (e.g. ProductArray[2], ProductArray[2, 4], ProductArray[2, 4, 6-8] respectively)

Response

The response is HTTP status code 200 (OK) for a successful variable read along with the resulting JSON data being the following:

{
  "apiVersion": "%ApiVersion%",
  "variables":
  [
    {
    "path": "%VariablePath1%",
    "value": %VariableValue1%
    },
    …
    {
    "path": "%VariablePathN%",
    "value": %VariableValueN%
    }
  ]
}

Description:

%ApiVersion% Version number of this API (e.g. v1.0)
%VariablePath1% Full path (i.e. path prefix + relative path) of the first variable (e.g. Arp.Plc.Eclr/Go, Arp.Plc.Eclr/PartArray)
%VariableValue1% Current value of the first variable (e.g. true) or the specified elements of the first array variable (e.g. 200, [200, 400], [200, 400, 600, 700, 800])
%VariableRelativePathN% Full path (i.e. path prefix + relative path) of the last variable (e.g. Arp.Plc.Eclr/CycleCount, Arp.Plc.Eclr/ProductArray)
%VariableValueN% Current value of the last variable (e.g. 100) or the specified elements of the last array variable (e.g. 250, [250, 450], [250, 450, 650, 750, 850]).

Otherwise, the appropriate HTTP status code (e.g. 400 = Bad Request, 408 = Request Timeout, 500 = Internal Server Error) is reported for a failed variable read.

Hide exampleClick to see an example

Example Request:

POST https://plc/_pxc_api/api/variables
Content-Type: text/plain; charset=utf-8

 

With the request body being the following:

pathPrefix=Arp.Plc.Eclr/&paths=PLC_SYS_TICK_CNT,SineWave

 

Example response with status code 200:

{
  "apiVersion": "1.1.0.3",
  "projectCRC": 2184605146,
  "userAuthenticationRequired": true,
  "variables": [
    {
    "path": "Arp.Plc.Eclr/PLC_SYS_TICK_CNT",
    "value": "1069839433"
    },
    {
    "path": "Arp.Plc.Eclr/SineWave",
    "value": -0.212013
    }
  ]
}

 

Write Variable(s)

Writes the requested value(s) to the specified variable(s). The resulting response being the variable value(s).

Case #1): Constant values

Request

Writes constant value(s) to the specified variable(s).

This is done via the following HTTP PUT command:

PUT https://%plcaddress%

With the accompanying JSON data being the following:

{
  "sessionID": "%OptionalSessionID%",
  "pathPrefix": "%OptionalVariablePathPrefix%",
  "variables":
  [
    {
    "path": "%VariablePath1%",
    "value": "%ConstantValue1%",
    "valueType": "Constant"
    },
    …
    {
    "path": "%VariablePathN%",
    "value": "%ConstantValueN%",
    "valueType": "Constant"
    }
  ]
}

Description:

%OptionalSessionID% Optionally assigned identifier for the current session (see Create a session) to implicitly avoid a session timeout or "" if that is unavailable
%OptionalVariablePathPrefix% Optionally desired path prefix for each of the variables (e.g. Arp.Plc.Eclr/)
%VariablePath1% Relative or full path of the first variable (e.g. CycleCount, Arp.Plc.Eclr/CycleCount respectively)
%ConstantValue1% Requested constant value for the first variable as a string (e.g. 0)
Constant Optional value type for the first variable as the default is constant
%VariablePathN% Relative or full path of the last variable (e.g. Go, Arp.Plc.Eclr/Go respectively)
%ConstantValueN% Requested constant value for the last variable as a string (e.g. 0)
Constant Optional value type for the last variable as the default is constant.

Response

The response is HTTP status code 200 (OK) for a successful variable write along with the resulting JSON data being the following:

{
  "apiVersion": "%ApiVersion%",
  "variables":
  [
    {
    "path": "%VariablePath1%",
    "value": %VariableValue1%,
    "uri": "%VariableUri1%"
    },
    …
    {
    "path": "%VariablePathN%",
    "value": %VariableValueN%,
    "uri": "%VariableUriN%"
    }
  ]
}

Description:

%ApiVersion% Version number of this API (e.g. v1.0)
%VariablePath1% Full path (i.e. path prefix + relative path) of the first variable (e.g. Arp.Plc.Eclr/CycleCount)
%VariableValue1% Written value of the first variable (e.g. 0)

%VariableUri1%

URL of the first variable to use for subsequent calls

%VariablePathN%

Full path (i.e. path prefix + relative path) of the last variable (e.g. Arp.Plc.Eclr/Go)

%VariableValueN%

Written value of the last variable (e.g. false)

%VariableUriN%

URL of the last variable to use for subsequent calls

Otherwise the appropriate HTTP status code (e.g. 400 = Bad Request, 408 = Request Timeout, 500 = Internal Server Error) is reported for a failed variable write.

Hide exampleClick to see an example

Example Request:

PUT https://plc/_pxc_api/api/variables
Content-Type: application/json

 

With the accompanying request body:

{
  "sessionID": "s1798554755",
  "pathPrefix": "Arp.Plc.Eclr/",
  "variables": [
    {
    "path": "BoolVar3",
    "value": "true",
    "valueType": "Constant"
    }
  ]
}

 

Example Response with status code 200:

{
  "apiVersion": "1.1.0.3",
  "projectCRC": 2373751656,
  "userAuthenticationRequired": true,
  "variables": [
    {
    "path": "Arp.Plc.Eclr/BoolVar3",
    "value": true,
    "uri": "/_pxc_api/api/variables/Arp.Plc.Eclr/BoolVar3"
    }
  ]
}

Case #2): Variable values

Request

Writes the current value(s) of the requested (source) variable(s) to the specified (destination) variable(s).

This is done via the following HTTP PUT command:

PUT https://%plcaddress%

With the accompanying JSON data being the following:

{
  "sessionID": "%OptionalSessionID%",
  "pathPrefix": "%OptionalVariablePathPrefix%",
  "variables":
  [
    {
    "path": "%WriteVariablePath1%",
    "value": "%ReadVariablePath1%",
    "valueType": "Variable"
    },
    …
    {
    "path": "%WriteVariablePathN%",
    "value": "%ReadVariablePathN%",
    "valueType": "Variable"
    }
  ]
}

Description: 

%OptionalSessionID% Optionally assigned identifier for the current session (see Create a session) to implicitly avoid a session timeout -or- "" if that is unavailable,
%OptionalVariablePathPrefix% Optionally desired path prefix for each of the variables (e.g. Arp.Plc.Eclr/),
%WriteVariablePath1% Relative or full path of the first (destination) variable to be written (e.g. Ingredient1Amount, Arp.Plc.Eclr/Ingredient1Amount respectively)
%ReadVariablePath1% Relative or full path of the first (source) variable to be read (e.g. Ingredient1Preset, Arp.Plc.Eclr/Ingredient1Preset respectively)
Variable Required value type for the first variable as the default is constant
%WriteVariablePathN% Relative or full path of the last (destination) variable to be written (e.g. IngredientNAmount, Arp.Plc.Eclr/IngredientNAmount respectively)
%ReadVariablePathN% Relative or full path of the last variable (e.g. IngredientNPreset, Arp.Plc.Eclr/IngredientNPreset respectively)
Variable Required value type for the last variable as the default is constant

The accompanying request body can also be a mix of the constant and variable value types.

Response

The response is HTTP status code 200 (OK) for a successful variable write along with the resulting JSON data being the following:

{
"apiVersion": "%ApiVersion%",
"variables":
  [
    {
    "path": "%WriteVariablePath1%",
    "value": %WriteVariableValue1%,
    "uri": "%WriteVariableUri1%"
    },
    …
    {
    "path": "%WriteVariablePathN%",
    "value": "%WriteVariableValueN%,
    "uri": "%WriteVariableUriN%"
    }
  ]
}

Description:

%ApiVersion% Version number of this API (e.g. v1.0)
%WriteVariablePath1% Full path (i.e. path prefix + relative path) of the first variable that was written (e.g. Arp.Plc.Eclr/Ingredient1Amount)
%WriteVariableValue1% Written value of the first variable (e.g. 100)

%WriteVariableUri1%

URL of the first variable that was written to use for subsequent calls
%WriteVariablePathN% Full path (i.e. path prefix + relative path) of the last variable that was written
(e.g. Arp.Plc.Eclr/IngredientNAmount)
%WriteVariableValueN% Written value of the last variable (e.g. 1000)
%WriteVariableUri1% URL of the last variable that was written to use for subsequent calls

Otherwise the appropriate HTTP status code (e.g. 400 = Bad Request, 408 = Request Timeout, 500 = Internal Server Error) is reported for a failed variable write.

Hide exampleClick to see an example

Example Request:

PUT https://plc/_pxc_api/api/variables
Content-Type: application/json

 

With the accompanying JSON data being the following:

{
  "sessionID": "1234567890",
  "pathPrefix": " Arp.Plc.Eclr/",
  "variables":
  [
    {
    "path": "Ingredient1Amount",
    "value": "Ingredient1Preset",
    "valueType": "Variable"
    },
    {
    "path": "IngredientNAmount",
    "value": "IngredientNPreset",
    "valueType": "Variable"
    }
  ]
}

 

Example Response with status code 200:

{
  "apiVersion": "v1.0",
  "variables":
  [
    {
    "path": " Arp.Plc.Eclr/Ingredient1Amount",
    "value": 100,
    "uri": "https://plc/_pxc_api/api/variables/ Arp.Plc.Eclr/ Ingredient1Amount"
    },
    {
    "path": " Arp.Plc.Eclr/IngredientNAmount",
    "value": 1000,
    "uri": "https://plc/_pxc_api/api/variables/ Arp.Plc.Eclr/ IngredientNAmount"
    }
  ]
}