REST data interface

This specification documents the REST-based approach used to exchange HTTP data with the PLCnext Control's firmware and with data in the Global Data Space (GDS). REST, or REpresentational State Transfer, is a software architecture style consisting of guidelines and best practices for creating scalable web services.

Note: This REST data interface is versioned, and each version is kept stable and will be maintained. We reserve for ourselves the possibility to make changes and additions in further versions that might lead to incompatibilities.

Therefore it is recommended to call this REST data interface out of your application explicitly with the version used during development, not with the latest key.

Reference

The following table summarizes the requests and their responses that are detailed in this document. To work with the following features on your PLCnext Control, make the REST data interface a protected resource as described here.

Command HTTP Method Relative URI for PLCnext Control Query Parameters Response
Service Description GET /_pxc_api/api
/_pxc_api/v1.0
  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 Variables via GET GET /_pxc_api/api/variables pathPrefix=%OptionalVariablePathPrefix%&paths=
%VariablePath1%,...,%VariablePathN%
JSON Data
Read Variables via POST POST /_pxc_api/api/variables (with request body
pathPrefix=%OptionalVariablePathPrefix%&paths=
%VariablePath1%,...,%VariablePathN%
)
JSON Data
Write Variables with Constant PUT /_pxc_api/api/variables (JSON Data with
%ConstantValue1% to %ConstantValueN%)
JSON Data
Write Variables with Variables 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.

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. As of the writing of this documentation, the current version path is v1.1.

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

GET https://%plcaddress%/api or
GET https://%plcaddress%

 

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

{
  "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://127.0.0.1:443/_pxc_api/api/rest",
    "@odata.context": "https://127.0.0.1:443/_pxc_api/api/$metadata",
    "value":  [
      {
      "name": "Variables",
      "kind": "EntitySet",
      "url": "variables"
      },
      {
      "name": "Groups",
      "kind": "EntitySet",
      "url": "groups"
      },
      {
      "name": "Sessions",
      "kind": "EntitySet",
      "url": "sessions"
      }
    ]
  }
}

resourcesPath and @odata.content are not implemented yet and may be provided in a future release.

In their place, provides data type information for the available HMI tags, and for the type definitions.