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.

Reporting 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

Examples

Hide the exampleClick to show an example

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

Creating Sessions

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:

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

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

Maintaining Sessions

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

Example

Hide the exampleClick to show an example

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

Reassigning Sessions

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

Example

Hide the exampleClick to show an example

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

Deleting Sessions

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