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.

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

Example

Hide the exampleClick to show an example

{
  "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

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

Example

Hide the exampleClick to show an example

{
  "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

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

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

Hide the exampleClick to show an example

{
  "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

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