Skip to content

REST Application Overview

This section describes how to build an application for an HCC2 using the example source code from the restapi_sample_interface repo that can be downloaded and installed from the previous section. This example code connects with HCC2 core apps using the REST API Interface or REST API Server.

This example is not intended to limit the use of other approaches or methodologies. For example, you can request data from the Modbus server on demand if this approach is more appropriate for your app behavior.

The high-level architecture of the app created with the sample code is presented in the figure below.

Application Architecture Block Diagram

The application structure is based on the following building blocks (see numbers above):

  1. Your application can interface directly with the HCC2 REST API Server. The HCC2 REST API Server is fully interoperable, so your application can be developed using any programming language that supports API calls.

  2. Your application, using the appropriate library, may issue REST operations to HCC2, such as GET, POST, PUT, DELETE, PATCH. A complete list of REST commands is available through REST API Swagger.

  3. The REST API Server also supports webhooks to asynchronously transfer data from the REST API Server to the application.

  4. If you don't wish to develop an API client framework for your application and your application can be written in Python, you may use a Sample Interface Class, provided in source code. It provides a full set of methods available for your application, so you are able to interface with REST API Server without implementing a full API Client interface. This class was developed in Python, so it is available only for applications written in Python.

  5. A Sample Interface Class in C# is also provided, in case you want to use C# as your programming environment.

  6. The application has access to read/write data from/to the memory storage using API methods. Those methods are:

    • For Python APIClient Object Instantiation 
      client = APIClient(app_name=<<myappname>>) # creates an API Client object to initialize interface with REST API Server.
      Connection with REST API 
      status = client.connect() # gets url from an env variable, validates url, and tests connection with REST API Server.
      Register Application into HCC2 
      response = client.registerApp(tarfile_path, is_complex_provisioned) # attempts to register the app to REST API Server, providing the tarball file.
      Check Provisioning Status 
      response = client.checkProvisioningStatus() # checks the current provisioning status of HCC2. If there are config changes, it returns True.
      Validate Provision 
      response = client.validateProvisioning(valid) # issues a message back to REST API allowing the app to validate (or not) the new configuration.
      Read Values from HCC2 
      response = client.messageRead(topic_list) # returns the current values of all topics listed in a topic_list.
response = client.messageReadAdvanced(topic_list) # returns the current values of all complex topics listed in a topic_list.
      Write Values to HCC2 
      response = client.messageWrite(datapoint_list) # writes back to REST API values to a set of topics listed in the datapoint_list.
response = client.messageWriteAdvanced(topic_list) # writes back to REST API values to a set of topics listed in the datapoint_list.

For a C# implementation, refer to the .Net REST Application Overview.