REST data interface - Requests

Overview to the requests

The following table summarizes the requests and their responses that are detailed in separate sections or topics. 

Command HTTP method Relative URI for PLCnext Control Query Parameters Response
Service Description GET /_pxc_api/api
/_pxc_api/v%Major%.%Minor% 		  JSON data
Report Sessions GET /_pxc_api/api/sessions   JSON data
Create Session POST /_pxc_api/api/sessions with request body stationID=%StationID%&timeout=%OptionalTimeout% JSON data
Maintain Session POST /_pxc_api/api/sessions/%SessionID%   JSON data
Reassign Session POST /_pxc_api/api/sessions/%SessionID% with request body stationID=%StationID%&timeout=%OptionalTimeout% JSON data
Delete Session DELETE /_pxc_api/api/sessions/%SessionID%   –
Report Groups GET /_pxc_api/api/groups   JSON data
Register Group POST /_pxc_api/api/groups/%GroupID% with request body pathPrefix=%OptionalVariablePathPrefix%&paths=
%VariablePath1%,...,%VariablePathN%		 JSON data
Read Group GET /_pxc_api/api/groups/%GroupID% summary=%OptionalSummarySetting% JSON data
Unregister Group DELETE /_pxc_api/api/groups/%GroupID%   –
Read Variable(s)
via GET		 GET /_pxc_api/api/variables pathPrefix=%OptionalVariablePathPrefix%&paths=
%VariablePath1%,...,%VariablePathN%		 JSON data
Read Variable(s)
via POST		 POST /_pxc_api/api/variables with request body pathPrefix=%OptionalVariablePathPrefix%&paths=
%VariablePath1%,...,%VariablePathN%		 JSON data
Write Variable(s) with constant values PUT /_pxc_api/api/variables JSON Data with %ConstantValue1% to %ConstantValueN% JSON data
Write Variable(s) with variable values PUT /_pxc_api/api/variables JSON Data with %ReadVariablePath1% to %ReadVariablePathN% JSON data

where

_pxc_api, api, v1.0, sessions, groups, and variables are virtual directories.

Note: To work with the above features on your PLCnext Control, first make the REST data interface a protected resource as described in the Authenticationtopic.

Service Description

The service description document is available at the root of the service.

It provides the version of the service in the form of v{Major}.{Minor}. The api path can be used to retrieve the latest version of the service.
The current version path is v1.1.

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.

Request

This is done via one of the following HTTP GET commands:

GET https://%plcaddress%/api
or
GET https://%plcaddress%/_pxc_api/v%Major%.%Minor%

where

%PlcAddress% is the address of the PLC,

%Major% is the API’s major version of 1, and 

%Minor% is the API’s minor version of 0 – 1.

Response

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

{
  "name": "PXCAPI",
  "apiVersion": "%ApiVersion%",
  "version": "%Version%",
  "userAuthenticationRequired": %UserAuthenticationRequired%,
  "title": "Lets you access PLC variables",
  "description": "Lets you access PLC variables",
  "ownerName": "Phoenix Contact",
  "protocol": "rest",
  "basePath": "%VersionPath%",
  "servicePath": "%VersionPath%",
  "metadata": 
  {
    "resourcesPath": "https://%PlcAddress%:443/_pxc_api%VersionPath%rest",
    "@odata.context": "https://%PlcAddress%:443/_pxc_api%VersionPath%$metadata",
    "value": 
    [
      {
        "name": "%ValueName1%",
        "kind": "EntitySet",
        "url": "%ValueUrl1%"
      },
      …
      {
        "name": "%ValueNameN%",
        "kind": "EntitySet",
        "url": "%ValueUrlN%"
      }
    ]
  }
}

where

%ApiVersion% is the version number of this API (e.g. 1.1.0.0)
%Version% is the version of this API (e.g. v1.1)
%UserAuthenticationRequired% is a Boolean indicating whether protected resources (variables, groups) require authentication
%VersionPath% is the version path of this API (e.g. /api/)
%PlcAddress% is the address of the PLC
%ValueName1% is the name of the first API metadata value (e.g. Variables)
%ValueUrl1% is the URL of the first API metadata value (e.g. Variables)
%ValueNameN% is the name of the last API metadata value (e.g.Groups)
%ValueUrlN% is the URL of the last API metadata value (e.g.Groups)

Note: resourcesPath and @odata.content are not implemented yet and may be provided in a future release of the REST data interface. In their place, https://%PlcAddress%/ehmi/data.dictionary.json provides data type information for the available HMI tags, and https://%PlcAddress%/ehmi/type.dictionary.json for the type definitions.

Example

Hide the exampleClick to show an example

Example request:

POST https://%PlcAddress%/_plc_api/api 

Example response with status code 200 (OK):

{
  "name": "PXCAPI",
  "apiVersion": "1.1.0.3",
  "version": "v1.1",
  "userAuthenticationRequired": true,
  "title": "Lets you access PLC variables",
  "description": "Lets you access PLC variables",
  "ownerName": "Phoenix Contact",
  "protocol": "rest",
  "basePath": "/api/",
  "servicePath": "/api/",
  "metadata": {
    "resourcesPath": "https://192.168.1.10:443/_pxc_api/api/rest",
    "@odata.context": "https://192.168.1.10:443/_pxc_api/api/$metadata",
    "value":  [
      {
      "name": "Variables",
      "kind": "EntitySet",
      "url": "variables"
      },
      {
      "name": "Groups",
      "kind": "EntitySet",
      "url": "groups"
      },
      {
      "name": "Sessions",
      "kind": "EntitySet",
      "url": "sessions"
      }
    ]
  }
}

 

See also

  1. Introduction
  2. Authentication
  3. Variables
  4. Groups
  5. Sessions
  6. Dictionaries

 

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