REST data interface - Sessions

If desired, the web server can track the set of active client stations based on their corresponding session information. Otherwise, the web server automatically considers each station to be anonymous.

Here's how session reports are managed.

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.

Report Sessions

This command reports the collection of currently active sessions on the web server (if any). The resulting report being a page with zero or more session identifiers & links along with a link to the next page (if any) until a complete listing of the currently active sessions is obtained.

Request

This is done via the following HTTP GET command:

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

where 

%PlcAddress% is the address of the PLC.

Response

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

{
  "apiVersion": "%ApiVersion%",
  "projectCRC": %ProjectCrc%,
  "userAuthenticationRequired": %UserAuthenticationRequired%,
  "sessions": [
    {
    "id": "%SessionID1%",
    "stationID": "%StationID1%",
    "ipAddress": "%IPAddress1%",
    "uri": "%SessionUri1%",
    "createdTimestamp": "%SessionCreatedTimestamp1%",
    "usedTimestamp": "%SessionUsedTimestamp1%",
    "timeout": "%SessionTimeout1%",
    "anonymous": %IsAnonymous1%,
    "disabled": %IsDisabled1%
    },
    …
    {
    "id": "%SessionIDN%",
    "stationID": "%StationIDN%",
    "ipAddress": "%IPAddressN%",
    "uri": "%SessionUriN%",
    "createdTimestamp": "%SessionCreatedTimestampN%",
    "usedTimestamp": "%SessionUsedTimestampN%",
    "timeout": "%SessionTimeoutN%",
    "anonymous": %IsAnonymousN%,
    "disabled": %IsDisabledN%
    }
  ],
  "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
%SessionID1% is the identifier of the first session on this report page (e.g. s20442639994)
%StationID1% is the station identifier that was supplied by the client when the first session on this report page was created
%IPAddress1% is the IP address of the client that created the first session in this report page
%SessisonUri1% is the full URI of the complete listing for the first session on this report page based on its identifier
(e.g. %PlcAddress%/_pxc_api/api/sessions/%SessionID1%)
%SessionCreatedTimestamp1% is the creation timestamp of the first session on this report page (e.g. 527984639), for informational purposes
%SessionUsedTimestamp1% is the last-used timestamp of the first session on this report page (e.g. 529534223), for informational purposes
%SessionTimeout1% is the time span in milliseconds after which the first session on this report page will be considered closed
%IsAnonymous1% is a Boolean indicating whether the client is communicating without using a station identifier for the first session on this report page
%IsDisabled1% is a Boolean indicating the disabled status for the first session on this report page
%SessionIDN% is the identifier of the last session on this report page (e.g. s21442666828)
%StationIDN% is the station identifier that was supplied by the client when the last session on this report page was created
%IPAddressN% is the IP address of the client that created the last session on this report page
%SessionUriN% is the full URI of the complete listing for the last session on this report page based on its identifier (e.g. %PlcAddress%/_pxc_api/api/sessions/%SessionIDN%)
%SessionCreatedTimestampN% is the creation timestamp of the last session on this report page (e.g. 527984639), for informational purposes
%SessionUsedTimestampN% is the last-used timestamp of the last session on this report page (e.g. 529534223 ), for informational purposes
%SessionTimeoutN% is the time in milliseconds after which the last session on this report page will be considered closed
%IsAnonymousN% is a Boolean indicating whether the client is communicating without using a station identifier for the last session on this report page
%IsDisabledN% is a Boolean indicating the disabled status for the last session on this report page
%NextUri% is literally null or the full URI for the next page of session numbers (i.e. N+1, ... , N+N) where required (e.g. %PlcAddress%/_pxc_api/api/sessions?page=2).

Examples

Hide the exampleClick to show an example

Example request:

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

Example response with status code 200:

{
  "apiVersion": "1.1.0.3",
  "projectCRC": 3389959845,
  "userAuthenticationRequired": true,
  "sessions": 
  [
    {
      "id": "s20442639994",
      "stationID": "0",
      "ipAddress": "192.168.1.100",
      "uri": "192.168.1.10:443/_pxc_api/api/sessions/s20442639994",
      "createdTimestamp": "442639994",
      "usedTimestamp": "442666526",
      "timeout": "5000",
      "anonymous": true,
      "disabled": false
    },
    {
      "id": "s21442666828",
      "stationID": "Welder1",
      "ipAddress": "192.168.248.8",
      "uri": "192.168.248.89:443/_pxc_api/api/sessions/s21442666828",
      "createdTimestamp": "442666828",
      "usedTimestamp": "442671093",
      "timeout": "5000",
      "anonymous": false,
      "disabled": false
    }
  ],
  "next": null
}

Create Session

This command creates a time-controlled session for a specific station. The resulting response being the session identifier and the session timeout.

Request

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

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

where

%PlcAddress% is the address of the PLC;

with the accompanying request body being the following:

stationID=%StationID%&timeout=%OptionalTimeout%

where

%StationID% is the station identifier (e.g. 10) for a known station, or 0 for an anonymous station, and

%OptionalTimeout% is the optionally desired timeout value in milliseconds (e.g. 1000).

Response

The response is HTTP status code 201 (Created) for a successful creation if such a known station did not already exist and a session was created
or
if multiple sessions are allowed due to it being an anonymous station and a session was created,

along with a customer header of "Location" with the full URI for the session (e.g. %PlcAddress%/_pxc_api/api/sessions/%SessionID%) and the resulting JSON data shown inthe following:

{
  "apiVersion": "%ApiVersion%",
  "projectCRC": %ProjectCrc%,
  "userAuthenticationRequired": %UserAuthenticationRequired%,
  "sessionID": "%SessionID%",
  "timeout": "%SessionTimeout%"
}

Description:

%ApiVersion% Version number of this API (e.g. "1.1.0.3")
%ProjectCRC% A checksum (CRC) that is typically used to detect HMI project changes (e.g., 2373751656)
%UserAuthenticationRequired% A Boolean indicating whether protected resources (variables, groups) require authentication
%SessionID% Automatically generated identifier for the session to ensure it is unique such as # (e.g. "s1721045074"). This session identifier needs to be included in all subsequent data requests.
%SessionTimeout% The resulting timeout value in milliseconds for the session (e.g. "5000"). It represents the poll rate at which the station promises to send session-based requests in order to avoid a session timeout.

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

Hide the exampleClick to show an example

Example Request:

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

with the accompanying request body being the following:

stationID=10&timeout=500

Example Response with status code 201 (Created):

{
  "apiVersion": "1.1.0.3",
  "projectCRC": 2373751656,
  "userAuthenticationRequired": true,
  "sessionID": "s1721045074",
  "timeout": "500"
}

Maintain Session

This command explicitly maintains a previously created session for an active client station in order to avoid a session timeout.

Request

This is done via the following HTTP POST command:

POST https://%PlcAddress%/_pxc_api/api/sessions/%SessionID%

where

%PlcAddress% is the address of the PLC and

%SessionID% is the assigned identifier for the session (e.g. s1721045074).

Response

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

{
  "apiVersion": "%ApiVersion%",
  "projectCRC": %ProjectCrc%,
  "userAuthenticationRequired": %UserAuthenticationRequired%,
  "sessionID": "%SessionID%"
}

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
%SessionID% is simply an echo of the assigned identifier of the session (e.g. s1721045074)

 

Example

Hide the exampleClick to show an example

Example request:

POST https://plc/_pxc_api/api/sessions/s1721045074

Example response with status code 200:

{
"apiVersion": "1.1.0.3",
"projectCRC": 2373751656,
"userAuthenticationRequired": true,
"sessionID": "s1721045074"
}

Reassign Session

This command reassigns a previously created session to a different station, with the resulting response being the new session identifier.

Request

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

POST https://%PlcAddress%/_pxc_api/api/sessions/%OldSessionID%

where

%PlcAddress% is the address of the PLC and

%OldSessionID% is the assigned identifier for the old/existing session (e.g. s1721045074);

with the accompanying request body the following:

stationID=%NewStationID%&timeout=%OptionalTimeout%

where

%NewStationID% is the new station identifier (e.g. 11) for a known station or either "" or 0 for an anonymous station and

%OptionalTimeout% is the optionally desired timeout value in millseconds (e.g. 1000)

Response

The response is HTTP status code 201 (Created) for a successful reassignment if such a known station did not already exist and a session was reassigned
or
if multiple sessions are allowed due to it being an anonymous station and a session was reassigned,
along with a customer header of "Location" with the full URI for the session (e.g. %PlcUri%/_pxc_api/api/sessions/%SessionID%) and the resulting JSON data shown in the following code block; otherwise, for a failed session reassignment the appropriate HTTP status code (e.g. 400 = Bad Request, 410 = Gone, 500 = Internal Server Error) is reported.

{
  "apiVersion": "%ApiVersion%",
  "projectCRC": %ProjectCrc%,
  "userAuthenticationRequired": %UserAuthenticationRequired%,
  "sessionID": "%NewSessionID%"
}

where

%ApiVersion% is the version number of this API (e.g. v1.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
%NewSessionID% is an automatically generated identifier for the new session to ensure it is unique (e.g. s1721045074); that session identifier needs to be included in all subsequent data requests

Example

Hide the exampleClick to show an example

Example request:

POST https://%PlcAddress%/_pxc_api/api/sessions/s1721045074

with the accompanying plain-text data being the following:

stationID=11

Example response with status code 200 (OK):

{
  "apiVersion": "1.1.0.0",
  "projectCRC": 2373751656,
  "userAuthenticationRequired": true,
  "sessionID": "s1721045074",
}

 

Delete Session

Request

This command deletes a previously created session with the following HTTP DELETE command:

DELETE https://%PlcAddress%/_pxc_api/api/sessions/%SessionID%

where

%PlcAddress% is the address of the PLC and

%SessionID% is the assigned identifier for the session (e.g. s1721045074).

Response

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

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

Hide exampleClick to see an example

Example Request:

DELETE https://%PlcAddress%/_pxc_api/api/sessions/s1721045074

Example Response with status code 204 only.

 

 


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