Skip to main content
Version IIoT Core
Hitachi Vantara Lumada and Pentaho Documentation

IIoT Core Services REST APIs

  1. Last updated
  2. Save as PDF

The IIoT Core Services REST APIs are used to convert manual processes into automated processes. Examples of frequently performed manual processes are asset deployment and redeployments and taking machines in and out of service. These operations can be automated using IIoT Core Services REST APIs.

Parent Topic
  • Use

    This guide describes the features of the IIoT Core Services UI and how to use them.

Child Topics

Prerequisites for using REST APIs
Parent Topic
  • IIoT Core Services REST APIs

    The IIoT Core Services REST APIs are used to convert manual processes into automated processes. Examples of frequently performed manual processes are asset deployment and redeployments and taking machines in and out of service. These operations can be automated using IIoT Core Services REST APIs.

Child Topics

Create a user in the KeyCloak interface

Create a user in the KeyCloak interface for accessing the IIoT Core Services REST APIs by performing the following steps.

Procedure

  1. Log in to the KeyCloak interface with the following information.

    KeyCloak master node server URLhtps://<cluster-fqdn>:30443/auth/
    Get the usernameecho $(kubectl get secret/credential-keycloak -o jsonpath='{ .data.ADMIN_USERNAME }' -n hiota | base64 -d)
    Get the passwordecho $(kubectl get secret/credential-keycloak -o jsonpath='{ .data.ADMIN_PASSWORD }' -n hiota | base64 -d)

  2. Select Users from the left navigation pane of KeyCloak UI.

  3. Click Add User.

  4. Enter the details for the new user.

  5. Click Save.

Results

The new user is created for accessing the IIoT Core ServicesIIoT Core Services REST APIs.
Parent Topic

Import API collection

Import the API collection from Swagger to Insomnia by performing the following steps.

Procedure

  1. Access the Swagger UI and click the swagger.json link.

    GUID-7AF6FF6A-CFB8-4E2B-9D45-BDF2F2B0724C-low.png

  2. The JSON code window appears. Download and save the JSON file on your local machine.

  3. Access the Insomnia UI, click Lumada IIoT Core Management V1 APIs, and then select Import/Export.

    GUID-6FD601A1-42C7-466F-938A-927E4CF86371-low.png

  4. The Insomnia Preferences dialog box appears. Click Import Data, and then select either of the following options:

    • Select From File, browse to locate the downloaded JSON file on your local machine, and click OK.

    • Select From URL and specify the following URL:

      https://<cluster-fqdn>:30443/docs/v1/ swagger_asset_managment.json

Results

The entire API collection is now imported from Swagger, and the API structure is displayed in the left navigation pane of the Insomnia UI.
Parent Topic

Generate a bearer authorization token in Keycloak

Generate a bearer authorization token from the KeyCloak interface by performing the following steps.

Procedure

  1. Access the Keycloak UI and select Auth Token from Keycloak server. The POST method with the Form tab opens.

  2. Verify the following parameter values and edit them, if required:

    • grant_type
    • scope
    • username
    • password
    • client_id
    • client_secret

  3. Click the Header tab and verify all the header information.

  4. Click Send to generate the authorization token.

    The response status code 200 OK indicates that the token is generated successfully.

Parent Topic

Set up the Swagger environment

Set up the Swagger environment using the generated token by performing the following steps.

Procedure

  1. Access the Swagger UI.

  2. Click Swagger env, and then Manage Environments.

  3. The Manage Environments window appears. Define the environment variables to set up the Swagger environment as displayed in the image below.

    GUID-BE6F53D9-D999-465F-B9B3-B0CDB0EACD1A-low.png

Parent Topic

Use REST APIs

Perform the following steps to create an asset type by using the Create Asset Type API in the Insomnia UI.

Procedure

  1. Access the Insomnia UI and click the Create Asset Type API from the left navigation pane.

  2. Select POST as the method for creating an asset type. The code for the POST method is displayed in the middle panel.

  3. Verify the parameter values and edit them, if required.

  4. Click Send to execute the API.

  5. Check the API response status code to verify the API execution status. The response code 200 OK represents a successful execution of the API and indicates that the new asset type is successfully created.

    The following standard response status codes are supported:

    Response status codeDescription
    200 OKResponse for a successful GET, PUT , PATCH, and DELETE.
    201 CreatedResponse for a successful POST.
    204 No contentSuccess with no additional content.
    400 Bad RequestClient-side input fails validation.
    401 UnauthorizedThe user is not authorized to access a resource or when the user is not authenticated.
    403 ForbiddenThe user is authenticated, but not allowed to access a resource.
    404 Not FoundThe resource is not found.
    500 Internal server errorGeneric server error. The server encountered an unexpected condition that prevented it from fulfilling the request.
    502 Bad GatewayInvalid response from an upstream server.
Parent Topic
  • IIoT Core Services REST APIs

    The IIoT Core Services REST APIs are used to convert manual processes into automated processes. Examples of frequently performed manual processes are asset deployment and redeployments and taking machines in and out of service. These operations can be automated using IIoT Core Services REST APIs.

View REST APIs

You can view IIoT Core REST APIs by performing the following steps.

Procedure

  1. In the IIoT Core Services UI, click the Administration tab, and then API documentation. The list of all the APIs appears.

  2. To view only APIs that are related to a specific function, select the function from the Select a definition field. For example, to view only asset management related APIs, select API Asset Management from the Select a definition field.

Parent Topic
  • IIoT Core Services REST APIs

    The IIoT Core Services REST APIs are used to convert manual processes into automated processes. Examples of frequently performed manual processes are asset deployment and redeployments and taking machines in and out of service. These operations can be automated using IIoT Core Services REST APIs.

Passport API

You can build your application using the IIoT Core Services Passport API to access data.

The IIoT Core Services Passport API supports user authentication for CouchDB, InfluxDB, Postgres, and MinIO data APIs. This allows you to add or revoke specific users at any time. This provides an additional layer of security for databases since its credentials are not usually required outside the server.

The Passport API authentication enables a proxy service using Kubernetes services for CouchDB, InfluxDB, Postgres, and MinIO databases (for port numbers, see Port configuration requirements (Core Services)). These ports receive requests that use Keycloak user names and passwords, validates those credentials with Keycloak via OAuth Helper, then sends the request to the appropriate database using the database credentials.

NoteThe Passport API does not support the use of the u and p query parameters, for user name and password respectively, in InfluxDB queries. All authentication must be done using standard basic authentication or OAuth tokens.
Protection from unauthorized data access

When querying the Influx database, make sure to protect from injections that lead to unauthorized data access.

You can opt to use bind parameters. Examples are available on docs.influxdata.com under bind parameters.

Parent Topic
  • IIoT Core Services REST APIs

    The IIoT Core Services REST APIs are used to convert manual processes into automated processes. Examples of frequently performed manual processes are asset deployment and redeployments and taking machines in and out of service. These operations can be automated using IIoT Core Services REST APIs.

Management plane REST API

IIoT Core Services provides management plane APIs for the following product features:

  • Asset management (including digital twin support)
  • Alert management
  • Kubernetes resource management

You can access management plane API descriptions, properties, and examples in the IIoT Core Services UI on the Administration tab under API Documentation.

For more information about how to use the management plane API, contact your Hitachi Vantara representative.

Parent Topic
  • IIoT Core Services REST APIs

    The IIoT Core Services REST APIs are used to convert manual processes into automated processes. Examples of frequently performed manual processes are asset deployment and redeployments and taking machines in and out of service. These operations can be automated using IIoT Core Services REST APIs.

Generate a bearer authorization token using REST API client

To generate a token, you can use Postman or any other REST API client.

Procedure

  1. Run the following REST API call to generate the ID token:

    POST https://<FQDN>:30443/auth/realms/default/protocol/openid-connect/token/
    Bearer authorization form fields Bearer authorization header fields

  2. Get the ID token in response.

  3. In the IIoT Core Services UI, click the Administration tab, and then click API Documentation.

  4. Click Authorize to create the authorization header.

  5. In the Value field, enter the word bearer followed by the previously generated bearer ID token to set the authorization header before testing your API.

    Authorize bearer ID token
Parent Topic
  • IIoT Core Services REST APIs

    The IIoT Core Services REST APIs are used to convert manual processes into automated processes. Examples of frequently performed manual processes are asset deployment and redeployments and taking machines in and out of service. These operations can be automated using IIoT Core Services REST APIs.