This content has moved to a new space on the Internet.

Go to new location

 


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: 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.

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%

Response

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

{
  "apiVersion": "%ApiVersion%",
  "groups":
  [
    {
    "id": "%GroupID1%",
    "variableCount": "%GroupVariableCount1%",
    "uri": "%GroupUri1%",
    "createdTimestamp": "%GroupCreatedTimestamp1%",
    "usedTimestamp": "%GroupUsedTimestamp1%"
    },
    …
    {
    "id": "%GroupIDN%",
    "variableCount": "%GroupVariableCountN%",
    "uri": "%GroupUriN%",
    "createdTimestamp": "%GroupCreatedTimestampN%",
    "usedTimestamp": "%GroupUsedTimestampN%"
    },
  ],
  "next": "%NextUri%"
}

Description:

%ApiVersion% Version number of this API (e.g. v1.0)
%GroupID1% Identifier of the first group on this page (e.g. 0)
%GroupVariableCount1% Number of variables in the first group on this page (e.g. 2), for informational purposes
%GroupUri1% 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% Creation timestamp of the first group on this page (e.g. yyyy/mm/dd hh:mm:ss), for informational purposes
%GroupUsedTimestamp1% Last-used timestamp of the first group on this page (e.g. yyyy/mm/dd hh:mm:ss), for informational purposes
%GroupIDN% Identifier of the last group (e.g. N-1)
%GroupVariableCountN% Number of variables in the last group on this page (e.g. 5), for informational purposes
%GroupUriN% 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% Creation timestamp of the last group on this page (e.g. yyyy/mm/dd hh:mm:ss), for informational purposes
%GroupUsedTimestampN% Last-used timestamp of the last group on this page (e.g. yyyy/mm/dd hh:mm:ss), for informational purposes
%NextUri% It is literally null or 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).

 

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

Hide exampleClick to see an example

Example Request:

GET https://plc/_pxc_api/api/groups

Example Response with status code 200:

{
  "apiVersion": "v1.0",
  "groups":
    [
      {
      "id": "0",
      "variableCount": "2",
      "uri": "https://plc/_pxc_api/api/groups/0",
      "createdTimestamp": "2018/01/02 03:04:05",
      "usedTimestamp": "2018/01/02 03:04:05"
      },
      {
      "id": "1",
      "variableCount": "5",
      "uri": "https://plc/_pxc_api/api/groups/1",
      "createdTimestamp": "2018/01/02 03:04:05",
      "usedTimestamp": "2018/01/02 03:04:05"
      },
    ],
    "next": null
}

Register Group

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%

with the request body being the following:

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

Description:

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

%OptionalVariablePathPrefix%

The 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%

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%/_pxc_api/api/groups/%GroupID%) and the resulting JSON data being the following:

{
  "apiVersion": "%ApiVersion%",
  "id": "%GroupID%",
  "variablePathPrefix": "%OptionalVariablePathPrefix%",
  "variables":
  [
    {
    "path": "%VariablePath1%",
    "type": "%VariableType1%"
    },
    …
    {
    "path": "%VariablePathN%",
    "type": "%VariableTypeN%"
    }
  ]
}

Description:

%ApiVersion% Version number of this API (e.g. v1.0)
%GroupID% Automatically generated identifier for the group to ensure it is unique such as "#" (e.g. 0, 1, etc.)
%OptionalVariablePathPrefix% Literally null or the path prefix for each of the variables (e.g. Arp.Plc.Eclr/; null),
%VariablePath1% Relative or full path of the first variable (e.g. Go, Arp.Plc.Eclr/Go respectively; PartArray)
%VariableType1% IEC data type of the first variable (e.g. BOOL; IntArray)
%VariablePathN% Relative or full path of the last variable (e.g. CycleCount, Arp.Plc.Eclr/CycleCount respectively; ProductArray)
%VariableTypeN% IEC data type of the last variable (e.g. INT; IntArray)

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

Hide exampleClick to see an example

Example Request:

POST https://plc
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:

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

Read Group

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%/

Description:

%GroupID% The assigned identifier for the group (e.g. 0, 1, etc.)
%OptionalSessionID% The optionally assigned identifier for the current session (see Create_a_session) to implicitly avoid a session timeout or "" if that is unavailable
%OptionalSummarySetting% 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 being the following:

{
  "apiVersion": "%ApiVersion%",
  "id": "%GroupID%",
  "variablePathPrefix": "%OptionalVariablePathPrefix%",
  "variables":
  [
    {
    "path": "%VariablePath1%",
    "type": "%VariableType1%",
    "value": %VariableValue1%
    },
    …
    {
    "path": "%VariablePathN%",
    "type": "%VariableTypeN%",
    "value": %VariableValueN%
    }
  ]
}

Description:

%ApiVersion% Version number of this API (e.g. v1.0)
%GroupID% Identifier for the group (e.g. 0,1, etc.)
%OptionalVariablePathPrefix% Literally null or the 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; PartArray)
%VariableType1% IEC data type of the first variable (e.g. BOOL; IntArray)
%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])
%VariablePathN% Relative or full path of the last variable (e.g. CycleCount, Arp.Plc.Eclr/CycleCount respectively; ProductArray)
%VariableTypeN% IEC data type of the last variable (e.g. INT; IntArray)
%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])

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 being the following:

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

Description:

%ApiVersion% Version number of this API (e.g. v1.0)
%VariableValue1% Current value of the first variable (e.g. 1) or the specified elements of the first array variable (e.g. 200, [200, 400], [200, 400, 600, 700, 800])
%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 group read.

Hide exampleClick to see an example

Example Request:

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

Example Response with status code 200:

{
  "apiVersion": "1.1.0.3",
  "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

Unregisters a previously registered group. The resulting response simply being whether that was successful.

Request

This is done via the following HTTP DELETE command:

DELETE https://%plcaddress%sessionID=%OptionalSessionID%

Description:

%GroupID% Assigned identifier for the group (e.g. 0, 1, etc.)
%OptionalSessionID% 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, the response is HTTP status code 204 (No Content) for a successful group unregistration, 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 exampleClick to see an example

Example Request:

DELETE https://plc/_pxc_api/api/groups/g1798554806/?sessionID=s1798554755

Example Response with status code 204:

The response body is empty.

 

 

 

 


 • Published/reviewed: 2020-08-07 • Revision 35 •