Overview

This OPC UA RESTful API exposes services in OPC UA Servers as http endpoints. The API is generic and shall work for all OPC UA Servers supporting the services which are exposed. This API consists in fact of two APIs. One API is purely http RESTful, and the other exposes an SignalR hub which enables real-time callbacks to clients. The two APIs are somewhat overlapping in functionality, but only the SignalR API has subcriptions for real-time data values and events.

The format of the data being transported back and forth between server and client is Json. This documentation lists the data types used in the API, and will show how these data types are represented in Json. The same data types are used in SignalR and the RESTful API.

Getting started

The API is a .Net 6 application, and it will run on all platforms supported by .Net 6. The application may be hosted in different enviroments (e.g. IIS for windows). The default host is Kestrel.

Make sure .Net 6 is installed on the computer. Download .Net 6

Hosting

This article describes how to host the application.

Kestrel

The default hosting environment is Kestrel. Simply run the Prediktor.OpcUa.Api.exe to host in Kestrel.

The endpoints used by Kestrel are by default http://localhost:5000 and https://localhost:5001.

This can be changed as shown here.

Licensing

This application is licensed. The licensing system stores the license on disk at an undisclosed location. This means that when running the application it should have write access to disk.

The API exposes endpoints for handling licenses.

GET
​/license
Tests if a valid license is in place

POST
​/license​/activate_online
Activates a license online

GET
​/license​/generate_offline_request
Generates offline activation requests.

POST
​/license​/activate_offline
Activates license offline

The license is activated by retreiving a license key from Prediktor. This key should be distributed with the API. If that is not the case please contact Prediktor to get a license key.

When you have a valid license key, the key can be posted in the /license/activate_online endpoint. It is only necessary to do this once. However, if the application is deleted/updated the license has to be actived again.

In-memory license

If hosted in an environment which does not have write permissions to disk, the appsettings.json must be changed to include the license key.

Add or uncomment the following:

  "License": {  
    "Key": "<enter key here>",  
    "Store": "memory"  
  },  

Authentication

The authentication can be enabled by adding:

"EnableAuthentication": true

to the appsettings.json.

The authentication used is JWT bearer authentication.

OPC UA settings

The API application contains an OPC UA Client, this client has a few settings which can be tweaked. It is, however, not encouraged to change those settings without having a thorough understanding of how the settings affect the application.

The settings are stored in the uaclient.xml file.

OPC UA certificates

The UA communication can be done in a secure or unsecure way. The Connection datatype decides if the connection is secure or not. It is highly encouraged to use a secure connection in a production environment.

If a secure connection is used, the client needs to have a valid certificate. The uaclient.xml file decides where these certificate files are located. If a valid certificate is not present, the application will create one. This certificate will be a self-signed certificate, and thus may not be automatically accepted and trusted by the OPC UA Server.

The default content of the uaclient.xml is:

<ApplicationCertificate>
  <StoreType>Directory</StoreType>
  <StorePath>%ProgramData%/Prediktor/opcuaapi/Config/pki</StorePath>
  <SubjectName>OPC UA API</SubjectName>
</ApplicationCertificate>

Some OPC UA servers have a way of trusting self-signed certificates, please take a look at the documentation for the OPC UA Server in question.

It is also possible to get a hold of a certificate from a trusted certificate issuer. This certificate must have a SubjectName equal to the subject name in the uaclient.xml file. (OPC UA API is the default subject name.)

OPC UA Namespaces

In OPC UA Servers there are one or more namespaces. Nodes belong to a namespace. The namespace is identified by a URL, however, due to the ubiquity of nodes, and the need to send node information back and forth between the server and clients, namespace indices are commonly used. The namespace index refer to the index of the namespace URL in a namespace array. The namespace array is exposed by the OPC UA Server. The namespace array may change during the life time of the OPC UA Server.

This means that a namespace index does not necessarily refer to the same namespace url, for instance after a restart of the OPC UA Server. To alleviate this problem somewhat it is possible for the client to send a namespace array in requests which will be mapped to the actual namespace array on the server.

Example:

A client uses nodes in namespaces called "ns1" and "ns2". In a call to the server the client can send over a namespace table like {"http://opcfoundation.org/UA/", "ns1", "ns2"}. Note that the first element in the namespace table must always be: "http://opcfoundation.org/UA/". All the node ids the client send over in the call will refer to this namespace table regardless of the status of the namespace table on the server. In this case the node id can for instance refer to namespace index 2 meaning "ns2".

OpenAPI

OpenAPI is used to describe the REST API.

Make sure the OPC UA API application is running.

Navigate to https://localhost:5001/index.html in a web browser to see the Swagger UI which can be used to test the REST API.

Read a value with Swagger UI

Open https://localhost:5001/index.html in a web browser, and find the /values/get endpoint.

Expand the node and click Try it out.

Change the entries to something that is available in a an OPC UA server.

Example:

 [  
     {
         "NodeIds":[
             {
                 "IdType":1,
                 "Id":"V|Worker.Signal1",
                 "Namespace":1
             }
         ],
         "ClientNamespaces":[
             "http://opcfoundation.org/UA/",
             "urn:prediktor:UAA-W2019-01:Solar"
         ],
         "Connection":{
             "Url":"opc.tcp://10.100.59.218:4852",
             "AuthenticationType":1
         }
     }
 ]

Click execute.

The respons will contain something like this if everything went OK.

[
  {
    "Values": [
      {
        "Value": {
          "Type": 10,
          "Body": 54
        },
        "SourceTimestamp": "2021-12-16T08:58:18.9825545Z",
        "ServerTimestamp": "2021-12-16T08:58:18.9825545Z"
      }
    ],
    "ServerNamespaces": [
      "http://opcfoundation.org/UA/",
      "http://prediktor.no/apis/ua/",
      "urn:prediktor:UAA-W2019-01:Solar",
      "http://scatecsolar.com/Enterprise",
      "http://scatecsolar.com/JO-GL",
      "http://scatecsolar.com/JO-GM",
      "http://prediktor.no/PVTypes/"
    ],
    "Success": true
  }
]

SignalR API

The SignalR API utilizes the Microsoft SignalR library. SignalR is a library for developers that simplifies the process of adding real-time web functionality to applications. Real-time web functionality is the ability to have server code push content to connected clients instantly as it becomes available, rather than having the server wait for a client to request new data.

In the OPC UA API the SignalR API is primarily used for subscribing to data and event values. This means that the API calls back to the client (e.g browser), when values have changed.

The SignalR API exposes a set of RPC-methods. The client must then implement corresponding callback methods to receive results fromt the API.

Hub

The address of the SignalR hub is /OpcUaHub.

The methods below can be reached through this hub.

Methods

ReadValues

This method is called to read values (i.e. the value of attribute with id = 13) of one or more nodes.

OnReadValues

This is the callback method for ReadValues.

The second parameter is an array of ReadValuesResponse, and contains the values (i.e. the value of attribute with id = 13) of the nodes or an error code if unsuccessful. The order of the arrays are the same as the order of the arrays in ReadValues.

WriteValues

This method is called to write values (i.e. the value of attribute with id = 13) to one or more nodes.

OnWriteValues

This is the callback method for WriteValues.

ReadDataTypes

This method is called to read datatypes (i.e. the value of attribute with id = 14) of one or more nodes.

OnReadDataTypes

This is the callback method for ReadDataTypes.

ReadAttributes

This method is called to read attributes of one or more nodes.

OnReadAttributes

This is the callback method for ReadAttributes.

The second parameter is an array of ReadAttributesResponse, and contains the values of the attributes or an error code if unsuccessful. The order of the arrays are the same as the order of the arrays in ReadAttributes.

WriteAttributes

This method is called to write attributes to one or more nodes.

OnWriteAttributes

This is the callback method for WriteAttributes.

HistoryReadRaw

This method reads raw history data from an OPC UA Server.

OnOnHistoryReadRaw

This is the callback method for HistoryReadRaw.

HistoryReadProcessed

This method reads processed data from an OPC UA Server.

OnHistoryReadProcessed

This is the callback method for HistoryReadProcessed.

GetHistoricalAggregates

This method gets the available historical aggregates from an OPC UA Server.

OnGetHistoricalAggregates

This is the callback method for GetHistoricalAggregates.

HistoryWriteValues

This method writes historical data to an OPC UA Server.

OnHistoryWriteValues

This is the callback method for HistoryWriteValues.

ReadEventsHistory

This method reads the event history from an OPC UA Server.

OnReadEventsHistory

This is the callback method for ReadEventsHistory.

ReadEventsHistoryExtended

This method reads the event history from an OPC UA Server. The difference between this method and ReadEventsHistory is that the fields to be queried for are not predefined.

OnReadEventsHistoryExtended

This is the callback method for ReadEventsHistoryExtended.

WriteEventsHistory

This method writes event history to an OPC UA Server.

OnWriteEventsHistory

This is the callback method for WriteEventsHistory.

WriteEventsHistoryExtended

This method writes event history to an OPC UA Server.

OnWriteEventsHistoryExtended

This is the callback method for WriteEventsHistoryExtended.

GetEventFields

This method gets the predefined event fields. These event fields are usually the most queried, and are available for querying in an easy way. This can be seen in ReadEventHistoryRequest.

OnEventFieldsFetched

This is the callback method for GetEventFields.

GetEventTypes

This method gets Event types.

OnGetEventTypes

This is the callback method for GetEventTypes.

AddEventComments

This method adds comment to an event.

OnEventsCommented

This is the callback method for AddEventComments.

ConfirmEvents

This method confirms events.

OnEventsConfirmed

This is the callback method for ConfirmEvents.

AcknowledgeEvents

This method acknowledges events.

OnEventsAcknowledged

This is the callback method for AcknowledgeEvents.

CreateEventSubscription

This method creates an event subscription. When subscribing to events two callback methods are involved. First the OnEventSubscriptionCreated is invoked telling whether the subscription was created correctly. Then as events happen the OnEvents method will be invoked, containing all the events which have occured since the last OnEvents call. The first OnEvents call after a successful event subscription has occured, will contain the current state of all the applicable event sources.

OnEventSubscriptionCreated

This is the callback method invoked after the CreateEventSubscription has been called.

OnEvents

This is the callback method invoked when the events have occured for the subscription.

CloseEventSubscription

This method closes (stops) an event subscription. If this method is not called, it will be automatically called when the client disconnects.

OnEventSubscriptionClosed

This is the callback method for CloseEventSubscription.

CreateDataValueSubscription

This method creates a data value subscription. When subscribing to data values two callback methods are involved. First the OnDataValueSubscriptionCreated is invoked telling whether the subscription was created correctly. Then as data values change the OnDataValuesUpdate method will be invoked, containing all the data values which have changed since the last OnDataValuesUpdate call.

OnDataValueSubscriptionCreated

This is the callback method invoked after the CreateDataValueSubscription has been called.

OnDataValuesUpdate

This is the callback method invoked when the data values have changed for the subscription.

CloseDataValueSubscription

This method closes (stops) a data value subscription. If this method is not called, it will be automatically called when the client disconnects.

OnDataValueSubscriptionClosed

This is the callback method for CloseDataValueSubscription.

StartDataValueSubscription

This method starts a subscription created by CreateDataValueSubscription.

OnDataValueSubscriptionStarted

This is the callback method for StartDataValueSubscription.

GetNamespaces

This method gets the namespaces of a OPC UA Server.

OnNamespacesFetched

This is the callback method for GetNamespaces.

Browse

This method is used to browse the UA Address Space for nodes.

OnBrowse

This is the callback method for Browse.

BrowseMulti

This method is used to browse with multiple source nodes the UA Address Space for nodes.

OnBrowseMulti

This is the callback method for BrowseMulti.

BrowseChildren

This method is used to browse the UA Address Space for children nodes. The children nodes are defined as nodes of node class: Variable, Object, DataType, VariableType or ObjectType.

OnBrowseChildren

This is the callback method for BrowseChildren.

BrowseProperties

This method is used to browse the UA Address Space for properties. The property nodes are defined as nodes of node class: Variable which has a HasProperty reference.

OnBrowseProperties

This is the callback method for BrowseProperties.

BrowsePropertiesMulti

This method is used to browse the UA Address Space for properties. The property nodes are defined as nodes of node class: Variable which has a HasProperty reference.

OnBrowsePropertiesMulti

This is the callback method for BrowsePropertiesMulti.

TranslateBrowsePathsToNodeIds

Translates browse paths to node ids.

OnTranslateBrowsePathsToNodeIds

This is the callback method for TranslateBrowsePathsToNodeIds.

Data types

The OPC UA API utilizes different data types. Some of the data types are defined by the OPC UA Foundation and use the OPC UA Foundation JSON serializers. The documentation will list the data types used and show the corresponding JSON and default values. The default values are used when they are not set.

Note that the JSON is case-sensitive

SignalR and RESTFul API Data types

The following types are exposed directly in the API. They consist of smaller data types which are referenced further down in the document.

Connection

Used when creating a connection.

ReadValuesRequest

Used when reading values (i.e. value of attributes with id = 13).

ReadValuesResponse

This the response when reading values of nodes.

WriteValuesRequest

Used when writing values (i.e. value of attributes with id = 13).

WriteNodeValue

Contains a NodeId and a DataValue. Is used when writing values.

WriteValuesResponse

This the response when writing values to a node.

ReadDataTypesRequest

Used when reading datatypes

ReadDataTypesResponse

This the response when reading data types of nodes.

DataTypeInfo

ReadAttributesRequest

Used when reading attributes. The ReadValueIds is an array of node ids and the attribute id it will read.

See Attributes.

ReadAttributesResponse

This the response when reading attributes.

WriteAttributesRequest

Used when writing attributes.

See Attributes.

WriteAttributesResponse

This the response when writing attributes.

ReadHistoryRawValuesRequest

Used when reading raw history data.

ReadHistoryRawValuesResponse

Response when reading raw history.

HistoryReadValueId

HistoryDataValueResult

Represents a historical read result for one node id.

ReadHistoryProcessedValuesRequest

Used when reading processed history data.

HistoryAggregateReadValueId

ReadHistoryProcessedValuesResponse

Response when reading processed history.

HistoryAggregateRequest

Used when getting aggregates from a server.

HistoryAggregateResponse

Response when reading history aggregates.

HistoryAggregate

Represents one aggregate option.

HistoryWriteRequest

Used when writing historical data to an OPC UA Server.

UpdateDataDetails

HistoryWriteResponse

Response when writing historical data.

HistoryUpdateResult

ReadEventHistoryRequest

Used when reading event history.

SimpleWhereClause

Represents a where clause in an event history query.

SimpleExpression

Represents a logical expression used in an event history query.

ReadEventHistoryResponse

Response when reading event history.

HistoryEventResult

EventMessage

Represents a single event. The fields may not be present if the Request does not include the field.

WriteEventHistoryRequest

EventHistoryUpdate

WriteEventHistoryResponse

ReadEventHistoryExtendedRequest

ReadEventHistoryExtendedResponse

HistoryEventExtendedResult

HistoryEventFieldList

WriteEventHistoryExtendedRequest

WriteEventHistoryExtendedResponse

EventFieldDefinition

Represents a predefined event field.

GetEventTypesRequest

Used when getting event types.

GetEventTypesResponse

The response when getting event types.

EventType

AddCommentRequest

This is used when adding a comment to an event.

AddCommentResponse

The response when adding a comment.

ConfirmRequest

This is used when confirming an event.

ConfirmResponse

The response when confirming an event.

AcknowledgeRequest

This is used when acknowledging an event.

AcknowledgeResponse

The response when acknowledging an event.

CreateEventSubscriptionRequest

This is used when creating a subscription for events.

CreateEventSubscriptionResponse

The response when creating an event.

EventsChangedResponse

The response when an event occurs.

CloseEventSubscriptionRequest

This is used when closing a subscription for events.

CloseEventSubscriptionResponse

The response when closing an event subscription.

CreateDataValueSubscriptionRequest

This is used when creating a data value subscription

DataValueMonitoredItem

This data type contains information regarding subscription of an item. The ClientHandle must set to a unique string for each node.

DataChangeFilter

This filter decides when a data value is deemed to have changed.

CreateDataValueSubscriptionResponse

The response when querying for namespaces.

DataValuesChangedResponse

When data values have changed this is sent to the subscriber.

NodeIdDataValue

Represents a change value. The ClientHandle corresponds to the ClientHandle in DataValueMonitoredItem.

CloseDataValueSubscriptionRequest

This is used when a data value subscription shall be closed.

CloseDataValueSubscriptionResponse

Returend when data value subscription has been called.

StartDataValueSubscriptionResponse

Returned when data value subscription has been started.

NamespacesRequest

NamespaceResponse

The response when querying for namespaces.

BrowseRequest

This is used when browsing for nodes.

BrowseMultiRequest

This is used when browsing for nodes.

BrowseNodes

BrowseResponse

The response after a Browse, BrowseNext or GetChildren call.

BrowseResult

MultiBrowseResponse

The response after a BrowseMulti, BrowsePropertiesMulti call.

ChildrenRequest

BrowsePropertiesRequest

BrowsePropertiesMultiRequest

TranslateBrowsePathsRequest

QualifiedNamePath

TranslateBrowsePathsResponse

BrowsePathResult

BrowsePathTarget

EventFilter

SimpleAttributeOperand

ContentFilter

From the OPC Foundation's OPC UA specification:

The ContentFilter structure defines a collection of elements that define filtering criteria. Each element in the collection describes an operator and an array of operands to be used by the operator. The operators that can be used in a ContentFilter are described in FilterOperator. The filter is evaluated by evaluating the first entry in the element array starting with the first operand in the operand array. The operands of an element may contain References to sub-elements resulting in the evaluation continuing to the referenced elements in the element array. The evaluation shall not introduce loops. For example evaluation starting from element A shall never be able to return to element A. However there may be more than one path leading to another element B.If an element cannot be traced back to the starting element it is ignored. Extra operands for any operator will result in an error.

ContentFilterElement

OPC UA Data types

ByteString

ByteString is a sequence of bytes.
A ByteString is represented by a base64 encoded string in JavaScript.

XmlElement

Represents an XML element.
Not supported

NodeId

The NodeId data type represents an OPC UA Node.

JSON Examples

Below are listed some JSON examples and the corresponding values.

ExpandedNodeId

A node id that stores the namespace URI instead of the namespace index.
TODO: Add

StatusCode

A StatusCode in OPC UA is numerical value that is used to report the outcome of an operation performed by an OPC UA Server. The StatusCode is a 32-bit unsigned integer. The top 16 bits represent the numeric value of the code that shall be used for detecting specific errors or conditions. The bottom 16 bits are bit flags that contain additional information but do not affect the meaning of the StatusCode.

See Status codes for possible status codes.

JSON Examples

QualifiedName

A string qualified with a namespace.

JSON Examples

LocalizedText

A localized text string with a locale identifier

JSON Examples

ExtensionObject

An opaque object with a syntax that may be unknown to the receiver Not supported

DiagnosticInfo

A diagnostic information associated with a result code

Limit

The Limit data type defines the structure to limit the request to a certain number of values.

ReadValueId

The ReadValueId data type is used when reading attributes.

JSON Examples

{"NodeId":{"IdType":1,"Id":"idxyz","Namespace":3},"AttributeId":13}

Variant

The variant represents a value. The value can be of a number of data types. The variant will be serialized differently depending on the actual data type it represents.
The different data types which can be represented by a variant is listed below.

The JavaScript data structure will look like this:

JSON Examples

DataValue

The data value is returned when reading an attribute.

WriteValue

The write value is used when writing an attribute.

JSON Examples

{"NodeId":{"IdType":1,"Id":"V|Worker.Write","Namespace":2},"AttributeId":13,"Value":{"Value":{"Type":8,"Body":"637709221331900544"}}}

ReferenceDescription

FilterOperator

The list below contains all the available filter operators used in SimpleExpression.

Note that not all of the operators make sense in a SimpleExpression.

TimestampsToReturn

This int can be 4 values:

BrowseDirection

This int can be 3 values:

NodeClass

A node class is represented by an int:

DataChangeTrigger

DeadbandType

PerformUpdateType

Primitive Data types

The common data types are the building blocks of the more complex data types. The data types are mapped to their corresponding JavaScript data types.

String

A string is a sequence of characters.
String is native to JavaScript.

Boolean

A boolean logic value (true or false).
Boolean is native to JavaScript.

SByte

An 8 bit signed integer value.
SByte is represented as a Numeric in JavaScript.

Byte

An 8 bit unsigned integer value.
Byte is represented as a Numeric in JavaScript.

Int16

A 16 bit signed integer value.
Int16 is represented as a Numeric in JavaScript.

UInt16

A 16 bit unsigned integer value.
UInt16 is represented as a Numeric in JavaScript.

Int32

A 32 bit signed integer value.
Int32 is represented as a Numeric in JavaScript.

UInt32

A 32 bit unsigned integer value.
UInt32 is represented as a Numeric in JavaScript.

Int64

A 64 bit signed integer value.
Int64 is represented as a Numeric in JavaScript.

UInt64

A 64 bit unsigned integer value.
UInt64 is represented as a Numeric in JavaScript.

Float

An IEEE single precision (32 bit) floating point value.
Float is represented as a Numeric in JavaScript.

Double

An IEEE double precision (64 bit) floating point value.
Double is represented as a Numeric in JavaScript.

GUID

A GUID is a 128-bit globally unique identifier.
A GUID will be represented as a string in a JavaScript-object.

Example:
"f114f6cf-31e0-43c8-9c22-399570312496"

DateTime

A DateTime represents a point in time.
A DateTime will be represented as a string in a JavaScript-object.

Example:

2021-11-11T16:00:00Z

Attributes

These are the attrbiutes defined in OPC UA.

Status codes

OPC UA Values REST API release notes

Release 0.4.8

• Fix: Removed license check from Api.

Release 0.4.1

• Feature: Added Limit to ReadHistoryRawValuesRequest, ReadEventHistoryRequest, ReadEventHistoryExtendedRequest

Release 0.3.0

• Feature: Changed browse, historyrawread, historyprocessedread and eventhistoryread. These methods no longer expose continuation points to clients.