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

Reporting sessions

Request

This GET command lists the active sessions on the web server.

GET https://%plcaddress%

Response

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

{
  "apiVersion": "1.1.0.3",
  "projectCRC": 3389959845,
  "userAuthenticationRequired": true,
  "sessions": [
    {
    "id": %SessionID1%,
    "stationID": %StationID1%,
    "ipAddress": %IPAddress1%,
    "uri": %SessionUri1%,
    "createdTimestamp": %SessionCreatedTimestamp1%,
    "usedTimestamp": %SessionUsedTimestamp1%,
    "timeout": %SessionTimeout1%,
    "anonymous": %IsAnonymous%,
    },
    […]
    {
    "id": "s21442666828",
    "stationID": %SessionIDN%,
    "ipAddress": %IPAddressN%,
    "uri": %SessionUriN%,
    "createdTimestamp": %SessionCreatedTimestampN%,
    "usedTimestamp": %SessionUsedTimestampN%,
    "timeout": %SessionTimeoutN%,
    "anonymous": %IsAnonymous%
    }
  ],
  "next": null
}

Description:

%ApiVersion% Version number of this API (e.g. v1.0)
%SessionID1% Identifier of the session
%StationID1% Station identifier that was supplied by the client when the session was created
%IPAddress1% IP address of the client that created the first session in the report
%SessisonUri1% Full URI of the complete listing for the session on this page based on its identifier
(e.g. %plcaddress%/_pxc_api/api/sessions/%SessionID1%)
%SessionCreatedTimestamp1% Last time the server had communication from the client on this session ID
(e.g. yyyy/mm/dd hh:mm:ss) for informational purposes
%SessionUsedTimestamp1% Last-used timestamp of the first session (e.g. yyyy/mm/dd hh:mm:ss) for informational purposes
%SessionTimeout1% Time in ms after which the session will be considered closed
%IsAnonymous1% Is true if the client is communicating without using a session ID
%SessionIDN% Identifier of the last session (e.g. N-1)
%StationIDN% Station identifier that was supplied by the client when the last session in the report was created
%IPAddressN% IP address of the client that created the last session in the report
%SessionUriN% Full URI of the complete listing for the last session in the report
%SessionCreatedTimestampN% Creation timestamp of the session (e.g. yyyy/mm/dd hh:mm:ss) for informational purposes
%SessionUsedTimestampN% The last time the server had communication from the client on this session ID
(e.g. yyyy/mm/dd hh:mm:ss) for informational purposes
%SessionTimeoutN% Time in ms after which the session will be considered closed
%IsAnonymousN% True if the client is communicating without using a session ID

 

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

Hide exampleClick to see an example

Example Request:

GET https://plc/_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.248.8",
    "uri": "192.168.248.89:443/_pxc_api/api/sessions/s20442639994",
    "createdTimestamp": "442639994",
    "usedTimestamp": "442666526",
    "timeout": "5000",
    "anonymous": true
    },
    {
    "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
    }
  ],
"next": null
}

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. %plcaddress%/_pxc_api/api/sessions/%SessionID%) and the resulting JSON data being the following:

{
"apiVersion": "%ApiVersion%",
"sessionID": "%NewSessionID%",
"timeout": %NewSessionTimeout%
}

Description:

%ApiVersion% Version number of this API (e.g. v1.0)
%NewSessionID% Automatically generated identifier for the new session to ensure it is unique such as # (e.g. 0, 1, etc.) The new session identifier needs to be included in all subsequent data requests
%NewSessionTimeout% Resulting timeout value in milliseconds for the new session (e.g. 100). 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, 408 = Request Timeout, 409 = Conflict, 500 = Internal Server Error) is reported for a failed session reassignment.

Hide exampleClick to see a plain-text content example

Example request:

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

with the accompanying plain-text data being the following:

stationID=11&timeout=500


Example Response with status code 201:

{
"apiVersion": "v1.0",
"sessionID": "1345678901",
"timeout": 500
}

Creating a session

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

Request

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

POST https://%plcaddress%

with the accompanying request body being the following:

stationID=%StationID%

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

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 being the 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 exampleClick to see 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:

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

Maintaining a session

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%

where %SessionID% is the assigned identifier for the session (e.g. 0, 1, etc.).

Response

The response is HTTP status code 200 (OK) for a successful session maintenance and the resulting JSON data being the following:

{
"apiVersion": "%ApiVersion%",
"sessionID": "%SessionID%"
}

Description:

%ApiVersion% The version number of this API (e.g. v1.0)
%SessionID% Echo of the assigned identifier of the session

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

Hide exampleClick to see an example

Example Request:

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

Example Response with status code 200:

{
"apiVersion": "1.1.0.3",
"projectCRC": 3977703988,
"userAuthenticationRequired": true,
"sessionID": "s1787539881"
}

Reassigning a session

This command reassigns a previously created session to a different station. 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%

where %OldSessionID% is the assigned identifier for the old/existing session (e.g. 0, 1, etc.),

with the accompanying request body the following:

stationID=%NewStationID%

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

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

{
"apiVersion": "%ApiVersion%",
"sessionID": "%NewSessionID%"
}

Description:

%ApiVersion% Version number of this API (e.g. v1.0),
%SessionID% Automatically generated identifier for the new session to ensure it is unique such as "#" (e.g. "s1721045074"). This session identifier needs to be included in all subsequent data requests.

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

Delete a session

Request

A previously created session is deleted with the following HTTP DELETE command:

DELETE https://%plcaddress%

where %SessionID% is the assigned identifier for the session (e.g. 0, 1, etc.).

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, the appropriate HTTP status code (e.g. 400 = Bad Request, 410 = Gone, 500 = Internal Server Error) is reported for a failed session deletion.

Hide exampleClick to see an example

Example Request:

DELETE https://plc/_pxc_api/api/sessions/1234567890

Example Response with status code 204:

n/a