4 Application Programming Interfaces (API) for Accessing the Cloud Library

4.1 General

4.1.1 OpenAPI

From https://spec.openapis.org/oas/v3.1.0.html:

“The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.”

4.1.2 Natural Language Search

“A natural language search is a search using regular spoken language, such as English. Using this type of search you can ask the database a question or you can type in a sentence that describes the information you are looking for. The database then uses a programmed logic to determine the keywords in the sentence by their position in the sentence.” See: https://www.usg.edu/galileo/skills/unit04/primer04_09.phtml

4.2 RESTful OpenAPI Definition of Cloud Library (mandatory)

Defined API endpoints shall follow REST principles as they are stateless. This decouples resources and representations. The data format for information exchange is JSON, therefore the encoding of existing OPC UA NodeSet files can be serialized to JSON (and consumed by the library), as well as being represented in the existing XML format. The new JSON format for the information models will be defined in an updated part 5 of the OPC UA spec.

The resource definitions of the REST API shall be defined self-descriptive using OpenAPI.

REST endpoints shall be provided for

search of information models

fuzzy search on information model metadata, but also custom fields like

commerce metrics (author, price, licence)

owner (who gets paid)

relationships from previous submissions (derivative info models, etc.)

retrieval and upload of information models

validation of information models before uploading

OpenAPI specification Version 3.0.1 is used.

Following is the formal definition of the interface methods:

4.2.1 Method Find

This method returns information model identifiers (implementation-specific) based on an array of keywords provided as input. The identifiers uniquely identify the information models stored in the UA Cloud Library.

Note: A recommended approach to generate these identifiers is to hash the NamespaceUri and the PublicationDate of the information model included in the nodeset file as these two fields uniquely identify an information model.

The keyword “*” (the asterisk character) an be used as a wildcard to return all information models currently available in the UA Cloud Library.

Signature

/informationmodel/find?keywords=”keyword”&keywords=”keyword2”

Parameters

None

Request Body Schema

None

Responses

Response Body Schema

[
  {
    "nodeset_id": uint,
    "nodesettitle": "string",
    "orgname": "string",
    "license": "string",
    "version": "string",
    "adressspacecreationtime": "2021-11-25T15:57:16"
  }
]

Comments

Fuzzy search may be implemented via the SQL ~ statement, i.e. to include information models that only partially match the search keywords.

4.2.2 Method Namespaces

This method returns all information model NameSpaceUris and associated information model identifiers of the information models found in the UA Cloud Library.

Signature

/informationmodel/namespaces

Parameters

None

Request Body Schema

None

Responses

Response Body Schema

[
	“string”
]

4.2.3 Method Names

This method returns all information model names and associated information model identifiers of the information models found in the UA Cloud Library.

Signature

/informationmodel/names

Parameters

None

Request Body Schema

None

Responses

Response Body Schema

[
	“string”
]

4.2.4 Method Download

This method returns a specific information model for the supplied information model identifier.

Signature

/informationmodel/download/{identifier}

Parameters

String Identifier (required) The information model identifier returned from any of the methods “find”, “namespaces” or “names”.

Request Body Schema

None

Responses

Response Body Schema

{
  "title": "string",
  "version": "string",
  "license": 0,
  "copyrightText": "string",
  "contributor": {
    "name": "string",
    "description": "string",
    "logoUrl": "string",
    "contactEmail": "string",
    "website": "string",
  },
  "description": "string",
  "category": {
    "name": "string",
    "description": "string",
    "iconUrl": "string",
  },
  "nodeSet": {
    "nodesetXml": "string",
    "publicationDate": "2022-01-25T19:52:09.664Z",
    "lastModifiedDate": "2022-01-25T19:52:09.664Z"
  },
  "documentationUrl": "string",
  "iconUrl": "string",
  "licenseUrl": "string",
  "keywords": [
    "string"
  ],
  "purchasingInformationUrl": "string",
  "releaseNotesUrl": "string",
  "testSpecificationUrl": "string",
  "supportedLocales": [
    "string"
  ],
  "numberOfDownloads": 0,
  "additionalProperties": [
    {
      "name": "string",
      "value": "string"
    }
  ]
}

4.2.5 Method Upload

This method uploads a specific information model to the UA Cloud Library.

Signature

/informationmodel/upload?overwrite=false

Parameters

Boolean overwrite (optional) An optional flag if an existing OPC UA information model with the same identifier found in the UA Cloud Library should be overwritten. Default value: false

Request Body Schema

{
  "title": "string",
  "version": "string",
  "license": 0,
  "copyrightText": "string",
  "contributor": {
    "name": "string",
    "description": "string",
    "logoUrl": "string",
    "contactEmail": "string",
    "website": "string",
  },
  "description": "string",
  "category": {
    "name": "string",
    "description": "string",
    "iconUrl": "string",
  },
  "nodeset": {
    "nodesetXml": "string",
    "publicationDate": "2022-01-25T19:55:07.348Z",
    "lastModifiedDate": "2022-01-25T19:55:07.348Z"
  },
  "documentationUrl": "string",
  "iconUrl": "string",
  "licenseUrl": "string",
  "keywords": [
    "string"
  ],
  "purchasingInformationUrl": "string",
  "releaseNotesUrl": "string",
  "testSpecificationUrl": "string",
  "supportedLocales": [
    "string"
  ],
  "numberOfDownloads": 0,
  "additionalProperties": [
    {
      "name": "string",
      "value": "string"
    }
  ]
}

Responses

Response Body Schema

string

Comments

Upload cannot overwrite a matching NameSpace from another organization.

The Namespace can be uniquely identified by its NamespaceUri and its PublicationDate and this is how the information model identifier can be generated. The reference implementation provided by the OPC Foundation on GitHub uses this approach.

4.3 GraphQL Query API Definition (optional)

Several Graph query interfaces exist today. GraphQL is popular and a good solution for building web APIs for all types of data stores and the one we chose. Alternatives are Gremlin and SPARQL (originally designed for querying RDF graphs). The GraphQL query API is an alternative to the mandatory REST interface described above and optional for the implementor. The GraphQL endpoint shall be /graphql.

GraphQL Schema

{
  "__validationErrors": [],
  "_queryType": "UACloudLibraryQuery",
  "_mutationType": null,
  "_subscriptionType": null,
  "_directives": [ "@include", "@skip", "@deprecated" ],
  "_typeMap": {
    "__DirectiveLocation": "__DirectiveLocation",
    "__TypeKind": "__TypeKind",
    "__EnumValue": "__EnumValue",
    "String": "String",
    "Boolean": "Boolean",
    "__Directive": "__Directive",
    "__InputValue": "__InputValue",
    "__Type": "__Type",
    "__Field": "__Field",
    "__Schema": "__Schema",
    "UACloudLibraryQuery": "UACloudLibraryQuery",
    "DatatypeType": "DatatypeType",
    "Int": "Int",
    "Long": "Long",
    "MetadataType": "MetadataType",
    "ObjecttypeType": "ObjecttypeType",
    "ReferencetypeType": "ReferencetypeType",
    "VariabletypeType": "VariabletypeType"
  },
  "_subTypeMap": {},
  "_implementationsMap": {}
}