REST data interface - Groups

If desired, the web server can manage the registered groups in order to make it easier to read a pre-defined list of variables. Otherwise, one can simply use the web server to read the variables directly.

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.
Usability tip: Use the in-topic navigation in the right sidebar to jump to a section of your interest.

Report Groups

This command reports the collection of currently registered groups (if any). The resulting report being a page with zero or more group names & links along with a link to the next page (if any) until a complete listing of the currently registered groups is obtained.

Request

This is done via the following HTTP GET command

GET https://%PlcAddress%/_plc_api/api/groups

where

%PlcAddress% is the address of the PLC.

Response

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

{ 
  "apiVersion": "%ApiVersion%", 
  "projectCRC": %ProjectCrc%,
  "userAuthenticationRequired": %UserAuthenticationRequired%, 
  "groups": 
  [ 
    {
      "id": "%GroupID1%", 
      "variableCount": "%GroupVariableCount1%", 
      "uri": "%GroupUri1%", 
      "createdTimestamp": "%GroupCreatedTimestamp1%", 
      "usedTimestamp": "%GroupUsedTimestamp1%", 
      "accessCount": "%GroupAccessCount1%", 
      "totalTimeAverage": "%GroupTotalTimeAverage1%", 
      "totalTimeMax": "%GroupTotalTimeMax1%", 
      "ehmiTimeAverage": "%GroupEhmiTimeAverage1%", 
      "ehmiTimeMax": "%GroupEhmiTimeMax1%", 
      "gdsTimeAverage": "%GroupGdsTimeAverage1%", 
      "gdsTimeMax": "%GroupGdsTimeMax1%" 
    }, 
    … 
    { 
      "id": "%GroupIDN%", 
      "variableCount": "%GroupVariableCountN%", 
      "uri": "%GroupUriN%", 
      "createdTimestamp": "%GroupCreatedTimestampN%", 
      "usedTimestamp": "%GroupUsedTimestampN%", 
      "accessCount": "%GroupAccessCountN%", 
      "totalTimeAverage": "%GroupTotalTimeAverageN%", 
      "totalTimeMax": "%GroupTotalTimeMaxN%", 
      "ehmiTimeAverage": "%GroupEhmiTimeAverageN%", 
      "ehmiTimeMax": "%GroupEhmiTimeMaxN%", 
      "gdsTimeAverage": "%GroupGdsTimeAverageN%", 
      "gdsTimeMax": "%GroupGdsTimeMaxN%" 
    } 
  ], 
  "next": "%NextUri%"
} 

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
%GroupID1% is the identifier of the first group on this page (e.g. g1527984639)
%GroupVariableCount1% is the number of variables in the first group on this page, for informational purposes
%GroupUri1% is the full URI of the complete listing for the first group on this page based on its identifier
(e.g. %PlcAddress%/_pxc_api/api/groups/%GroupID1%)
%GroupCreatedTimestamp1% is the creation timestamp of the first group on this page (e.g. yyyy/mm/dd hh:mm:ss), for informational purposes
%GroupUsedTimestamp1% is the last-used timestamp of the first group on this page (e.g. yyyy/mm/dd hh:mm:ss), for informational purposes
%GroupAccessCount1% is the number of times the first group on this report was accessed, for informational purposes
%GroupTotalTimeAverage1% are performance metrics of the first group on this report page, for diagnostic purposes
%GroupTotalTimeMax1%
%GroupEhmiTimeAverage1%
%GroupEhmiTimeMax1%
%GroupGdsTimeAverage1%
%GroupGdsTimeMax1%
%GroupIDN% is the identifier of the last group (e.g. N-1) on this report page (e.g. g2528118714)
%GroupVariableCountN% is the number of variables in the last group on this report page, for informational purposes
%GroupUriN% is the full URI of the complete listing for the last group on this page based on its identifier
(e.g. %PlcAddress%/_pxc_api/api/groups/%GroupIDN%)
%GroupCreatedTimestampN% is the creation timestamp of the last group on this page (e.g. yyyy/mm/dd hh:mm:ss), for informational purposes
%GroupUsedTimestampN% is the last-used timestamp of the last group on this page (e.g. yyyy/mm/dd hh:mm:ss), for informational purposes
%GroupAccessCountN% is the number of times the last group in this report page was accessed, for informational purposes 
%NextUri%

is literally null or
is the full URI for the next page of group members (i.e. N+1 … N+N) where required (e.g. %PlcAddress%/_pxc_api/api/groups?page=2).

Example

Hide the exampleClick to show an example

Example request:

GET https://%PlcAddress%/_pxc_api/api/groups

Example response with status code 200:

{
  "apiVersion": "v1.1",
  "projectCRC": 3389959845,
  "userAuthenticationRequired": true,
  "groups":
  [
    { 
      "id": "g1527984639",
      "variableCount": 23,
      "uri": "192.168.1.10:443/_pxc_api/api/groups/g1527984639",
      "createdTimestamp": "527984639",
      "usedTimestamp": "529536319",
      "accessCount": "687",
      "totalTimeAverage": "0",
      "totalTimeMax": "2",
      "ehmiTimeAverage": "0",
      "ehmiTimeMax": "1",
      "gdsTimeAverage": "0",
      "gdsTimeMax": "2"
    },
    {
      "id": "g2528118714",
      "variableCount": 16,
      "uri": "192.168.1.10:443/_pxc_api/api/groups/g2528118714",
      "createdTimestamp": "528118714",
      "usedTimestamp": "529534223",
      "accessCount": "424",
      "totalTimeAverage": "0",
      "totalTimeMax": "2",
      "ehmiTimeAverage": "0",
      "ehmiTimeMax": "0",
      "gdsTimeAverage": "0",
      "gdsTimeMax": "2"
    }
  ],
  "next": null
}

Register Group

This command registers a group for a supplied list of variables that can later be read together. The resulting response being the group name and the variable types.

Request

Since the web server will manage the registration details, this is done via the following HTTP POST command:

POST https://%PlcAddress%/_pxc_api/api/groups

where

%PlcAddress% is the address of the PLC,

with the request body being the following:

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

where

%OptionalSessionID% is the optionally assigned identifier for the current session (see Create a 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 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 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 201 (Created) for a successful registration if such a group did not already exist and was created, or HTTP status code 200 (OK) if such a group already existed and was reused, along with a customer header of "Location" with the full URI for the group (e.g. %PlcAddress%:443/_pxc_api/api/groups/%GroupID%) and the resulting JSON data being the following code block; otherwise, for a failed group registration 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%,
  "id": "%GroupID%",
  "variablePathPrefix": "%OptionalVariablePathPrefix%",
  "variables":
  [
    {
      "path": "%VariablePath1%",
      "type": "%VariableType1%"
    },
    …
    {
      "path": "%VariablePathN%",
      "type": "%VariableTypeN%"
    }
  ]
}

where

%ApiVersion% is the version number of this API (e.g. v1.1)
%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
%GroupID% is the automatically generated identifier for the group to ensure it is unique (e.g. g2798617204)
%OptionalVariablePathPrefix% is literally null or the path prefix for each of the variables (e.g. Arp.Plc.Eclr/; null),
%VariablePath1% is the relative or full path of the first variable (e.g. Go, Arp.Plc.Eclr/Go respectively; PartArray)
%VariableType1% is the IEC data type of the first variable (e.g. BOOL; IntArray)
%VariablePathN% is the relative or full path of the last variable (e.g. CycleCount, Arp.Plc.Eclr/CycleCount respectively; ProductArray)
%VariableTypeN% is the IEC data type of the last variable (e.g. INT; IntArray)

 

Example

Hide the exampleClick to show an example

Example request:

POST https://%PlcAddress%/_plc_api/api/groups
Content-Type: text/plain; charset=utf-8 

with the accompanying request body:

{"sessionID": "s1798554755", "pathPrefix": "Arp.Plc.Eclr/", "paths": ["PLC_SYS_TICK_CNT","SineWave3"] } 

Example response with status code 201 (Created):

{
  "apiVersion": "v1.1",
  "projectCRC": 2373751656,
  "userAuthenticationRequired": true,
  "id": "g2798617204",
  "variablePathPrefix": "Arp.Plc.Eclr/",
  "variables": 
  [ { "path": "PLC_SYS_TICK_CNT", "type": "DINT" }, { "path": "SineWave3", "type": "REAL" } ] }

 

Read Group

This command reads the values for a previously registered group’s variable list in the same order as they were originally supplied. The resulting response being the same group registration response along with the variable values.

Request

This is done via the following HTTP GET command:

GET https://%PlcAddress%/_pxc_api/api/groups/%GroupID%?sessionID=%OptionalSessionID%&summary=%OptionalSummarySetting%

where

%PlcAddress% is the address of the PLC
%GroupID% is the assigned identifier for the group (e.g. 0, 1, etc.)
%OptionalSessionID% is the optionally assigned identifier for the current session (see Create a session) to implicitly avoid a session timeout or "" if that is unavailable
%OptionalSummarySetting% is the optional summary setting for the group read (e.g. 0 is off, 1 is on)

with the summary setting being turned off (default), the response is HTTP status code 200 (OK) for a successful group read along with the resulting JSON data shown in the following code block:

{
  "apiVersion": "%ApiVersion%",
  "projectCRC": %ProjectCrc%,
  "userAuthenticationRequired": %UserAuthenticationRequired%,
  "id": "%GroupID%",
  "variablePathPrefix": "%OptionalVariablePathPrefix%",
  "variables":
  [
    {
      "path": "%VariablePath1%",
      "type": "%VariableType1%",
      "value": %VariableValue1%
    },
    …
    {
      "path": "%VariablePathN%",
      "type": "%VariableTypeN%",
      "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
%GroupID% is the identifier for the group (e.g. g2798617204)
%OptionalVariablePathPrefix% is literally null or the path prefix for each of the variables (e.g. Arp.Plc.Eclr/)
%VariablePath1% is the relative or full path of the first variable (e.g. Go, Arp.Plc.Eclr/Go respectively; PartArray)
%VariableType1% is the IEC data type of the first variable (e.g. BOOL; IntArray)
%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])
%VariablePathN% is the relative or full path of the last variable (e.g. CycleCount, Arp.Plc.Eclr/CycleCount respectively; ProductArray)
%VariableTypeN% is the IEC data type of the last variable (e.g. INT; IntArray)
%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])

Response

with the summary setting instead being turned on, the response is HTTP status code 200 (OK) for a successful group read along with the resulting JSON data shown in the following code block; otherwise, for a failed group read the appropriate HTTP status code (e.g. 400 = Bad Request, 408 = Request Timeout, 500 = Internal Server Error) is reported. 

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

where

%ApiVersion% is the version number of this API (e.g. 1.1.0.0)
%VariableValue1% is the current value of the first read variable (e.g. 1) or the specified elements of the first array variable (e.g. 200, [200; 400], [200; 400; 600; 700; 800])
%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])

 

Hide the exampleClick to show an example

Example request:

GET https://%PlcAddress%/_pxc_api/api/groups/g2798617204/?sessionID=s1798554755 

Example response with status code 200 (OK):

{
  "apiVersion": "v1.1",
  "projectCRC": 2373751656,
  "userAuthenticationRequired": true,
  "id": "g2798617204",
  "variablePathPrefix": "Arp.Plc.Eclr/",
  "variables": [
    {
      "path": "PLC_SYS_TICK_CNT",
      "value": "799244562"
    },
    {
      "path": "SineWave3",
      "value": -0.556875
    }
  ]
}

 

Unregister Group

This command unregisters a previously registered group, and the resulting response simply being whether that was successful.

Request

This is done via the following HTTP DELETE command:

DELETE https://%PlcAddress%/_pxc_api/api/groups/%GroupID%?sessionID=%OptionalSessionID%

where

%PlcAddress% is the address of the PLC
%GroupID% is the assigned identifier for the group (e.g. g2798617204)
%OptionalSessionID% is the optionally assigned identifier for the current session (see Create_a_session) to implicitly avoid a session timeout, or "" if that is unavailable.

 

Response

Due to the DELETE command, for a successful group unregistration the response is HTTP status code 204 (No Content), and not HTTP status code 200 (OK).

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

However, the web server has a timeout period (e.g. 120 seconds) where it will automatically unregister the group due to inactivity, so this is normally not necessary.

Hide the exampleClick to show an example

Example request:

DELETE https://%PlcAddress%/_pxc_api/api/groups/g2798617204/?sessionID=s1798554755

Example response with status code 204 (No Content):

The response body is empty.

 

 


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