REST data interface - Variables

Note: Phoenix Contact reserves 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)

This command 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).

Note: Global variables must have an HMI tag to be available for the REST API!

Case #1): Reading variables via GET

Request

This is done via the following HTTP GET command:

GET https://%PlcAddress%/_pxc_api/api/variables?sessionID=%OptionalSessionID%&pathPrefix=%OptionalVariablesPathPrefix%&paths=%VariablePath1%,...,%VariablesPathN%

where

%PlcAddress% is the address of the PLC
%OptionalSessionID% is the optionally assigned identifier for the current session to be maintained (see Maintain Session) to implicitly avoid a session timeout
or "" if that is unavailable
%OptionalVariablePathPrefix% is the optionally desired path prefix for each of the variables (e.g. Arp.Plc.Eclr/)

%VariablePath1%

 is the relative or the 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%

 is the relative or the 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 shown in the following code block; otherwise, for a failed variable read the appropriate HTTP status code (e.g. 400 = Bad Request, 408 = Request Timeout, 500 = Internal Server Error) is reported.

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

where

%ApiVersion% is the version number of this API (e.g. 1.1.0.0)
%ProjectCrc% is a  checksum (CRC) that is typically used to detect HMI project changes (e.g. 2373751656)
%UserAuthenticationRequired% is a Boolean indicating whether protected resources (variables, groups) require authentication
%VariablePath1% is the full path (i.e. path prefix + relative path) of the first variable (e.g. Arp.Plc.Eclr/Go, Arp.Plc.Eclr/PartArray)

%VariableValue1%

 is the 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%

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

%VariableValueN%

 is the 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])

Example

Hide the exampleClick to show an example

Example request:

GET https://%PlcAddress%/_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): Reading variables via POST

Request

Due to potential limits with the GET query string, reading can alternatively be done via the following HTTP POST command:

POST https://%PlcAddress%/_pxc_api/variables

where

%PlcAddress% is the address of the PLC;

with the accompanying plain-text data being the following:

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

where

%OptionalSessionID% is the optionally assigned identifier for the current session to be maintained (see Maintain Session) to implicitly avoid a session timeout
or "" if that is unavailable
%OptionalVariablePathPrefix% is the optionally desired path prefix for each of the variables (e.g. Arp.Plc.Eclr/)
%VariablePath1% is the relative or the 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% is the relative or the 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 shown in the following code block; otherwise, for a failed variable read the appropriate HTTP status code (e.g. 400 = Bad Request, 408 = Request Timeout, 500 = Internal Server Error) is reported.

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

where

%ApiVersion% is the version number of this API (e.g. 1.1.0.0)
%ProjectCrc% is a checksum (CRC) that is typically used to detect HMI project changes (e.g. 2373751656)
%UserAuthenticationRequired% is a Boolean indicating whether protected resources (variables, groups) require authentication
%VariablePath1% is the full path (i.e. path prefix + relative path) of the first variable (e.g. Arp.Plc.Eclr/Go, Arp.Plc.Eclr/PartArray)
%VariableValue1% is the current value of the first read variable (e.g. true)
or the specified elements of the first array variable (e.g. 200, [200; 400], [200; 400; 600; 700; 800])
%VariableRelativePathN% is the full path (i.e. path prefix + relative path) of the last variable (e.g. Arp.Plc.Eclr/CycleCount, Arp.Plc.Eclr/ProductArray)
%VariableValueN% is the current value of the last read variable (e.g. 100)
or the specified elements of the last array variable (e.g. 250, [250; 450], [250; 450; 650; 750; 850]).

Example

Hide the exampleClick to show an example

Example Request:

POST https://%PlcAddress%/_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)

This command writes the requested value(s) to the specified variable(s), the resulting response being the variable value(s).

Case #1): Writing constant values

Request

This is done via the following HTTP PUT command:

PUT https://%PlcAddress%/_pxc_api/api/variables

where

%PlcAddress% is the address of the PLC; 

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"
    }
  ]
}

where

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

Response

The response is HTTP status code 200 (OK) for a successful variable write along with the resulting JSON data is shown in the following code block; otherwise, for a failed variable write the appropriate HTTP status code (e.g. 400 = Bad Request, 408 = Request Timeout, 500 = Internal Server Error) is reported.

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

where

%ApiVersion% is the version number of this API (e.g. 1.1.0.0)
%ProjectCrc% is a checksum (CRC) that is typically used to detect HMI project changes (e.g. 2373751656)
%UserAuthenticationRequired% is a Boolean indicating whether protected resources (variables, groups) require authentication
%VariablePath1% is the full path (i.e. path prefix + relative path) of the first variable (e.g. Arp.Plc.Eclr/CycleCount)
%VariableValue1% is the written value of the first variable (e.g. 0)
%VariableUri1% is the URL of the first variable to use for subsequent calls
%VariablePathN% is the full path (i.e. path prefix + relative path) of the last variable (e.g. Arp.Plc.Eclr/Go)
%VariableValueN% is the written value of the last variable (e.g. false)
%VariableUriN% is the URL of the last variable to use for subsequent calls

 

Note: %VariableUri1% and %VariableUriN% are not implemented yet and may be provided in a future release.

Hide the exampleClick to show an example

Example Request:

PUT https://%PlcAddress%/_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): Writing variable values

This command writes the current value(s) of the requested (source) variable(s) to the specified (destination) variable(s).

Request

This is done via the following HTTP PUT command:

PUT https://%PlcAddress%/_plc_api/api/variables

where

%PlcAddress% is the address of the PLC,

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"
    }
  ]
}

where 

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

The accompanying request body can also be a mix of 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 shown in the following code block; otherwise,  for a failed variable write the appropriate HTTP status code (e.g. 400 = Bad Request, 408 = Request Timeout, 500 = Internal Server Error) is reported.

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

where

%ApiVersion% is the version number of this API (e.g. 1.1.0.0)
%WriteVariablePath1% is the full path (i.e. path prefix + relative path) of the first variable that was written (e.g. Arp.Plc.Eclr/Ingredient1Amount)
%VariableValue1% is the written value of the first variable (e.g. 100)

%WriteVariableUri1%

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

Note: %WriteVariableUri1% and %WriteVariableUriN% are not implemented yet and may be provided in a future release.

Example

Hide the exampleClick to show an example

Example Request:

PUT https://%PlcAddress%/_pxc_api/api/variables

Content-Type: application/json

with the accompanying JSON data being the following:

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

 Example Response with status code 200:

{
  "apiVersion": "1.1.0.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"
    }
  ]
}

 

 

 

See also

  1. Introduction
  2. Authentication
  3. Groups
  4. Sessions
  5. Requests
  6. Dictionaries

 

• Published/reviewed: 2024-09-24   ☀  Revision 073 •