REST Server Implementation

These topics are explained:

1. Preface (this page)
2. The workflow
3. The API

Overview

For a user-created application to comply and exist within the HCC2's runtime environment, it must follow certain rules. The HCC2 team has provided a set of tools to enable an application to correctly register itself and define any data points or user interface for the application business logic or a user to interact with. These properties are encapsulated in an application definition file, in the tar.gz compressed format. Throughout these pages, you will learn how to populate and maintain a tar.gz file and learn the workflows that must be followed during the development process and the application's runtime lifecycle.

Introduction

The REST server provides, as the name suggests, a RESTful API interface to other containers. The server exposes APIs that enable an application and/or developer, to perform the following tasks:

• Define an application's own data points
• Work with the configuration of an application
• Read/write the messages and data points in the HCC2

Each feature of the REST server is covered in a separate section.

Development Mode & Swagger UI

By default, the REST server is internal to the HCC2. This meets the needs of an application in the production environment.

However, for development, the REST endpoints must be accessible from outside the HCC2. To enable access, you must enable development mode in the HCC2 and open a firewall port.

Enable Development Mode

To enable development (aka dev) mode, install the following two licenses:

• HCC2 Edge App Enablement
• Edge HCC2 SDK Dev License

Swagger UI

Swagger is a framework and set of tools for designing, building, documenting, and consuming RESTful APIs. It helps developers standardize the API design and provides interactive documentation. It is an excellent tool for rapidly learning the API and all the data properties without writing any code. In addition, it provides the curl command, a useful command line tool for demonstrating how your application could interact with an endpoint in use.

To access the Swagger UI:

• Install the licenses mentioned above to enable the dev mode.
• Open port 7071 in the HCC2 firewall.
  • Access Unity at https://<<your HCC2 IP Address>>.
  • Go to Deploy->Device->User Firewall Port page.
  • Add port 7071/TCP for appropriate interface.
    • Click "Update Deployment File" button.
  • Go to Deploy->Deploy page.
    • Click "Start" button.
    • Click "Deploy" button.

• Access Swagger UI at http://<<your HCC2 IP Address>>:7071.

  Important

  You must open the firewall port for the interface that you are using to access the HCC2. For example, if accessing the HCC2 from USB, the HCC2 IP address is 169.244.1.1 and you would open 7071/TCP on the USB Interface.

Note that both Swagger and the REST API are available via an encrypted HTTPS channel. To access via HTTPS, use https://<<your HCC2 IP Address>>:7072. Ensure port 7072 is open in the HCC2 firewall.

Application Configuration Editor (ACE)

The Application Configuration Editor, aka ACE, is a Windows desktop tool that complements the REST APIs in defining an app and its data points.

The tool is for use offline. ACE is for advanced application data point and UI configuration, allowing bulk edits on data points and maintenance of any associated application web page to be deployed to the HCC2 to support the application being created. ACE can be used alone or in conjunction with the RESTful API.

If you are using ACE, you should not use Application Creation APIs of the REST.

You can see how ACE is used in the example application here.

Development Overview