How-to guide: Generate an API

Aspect on Demand enables you to convert your data lake information into custom APIs ("Aspect APIs"). In addition to that, Aspect on Demand stores the generated APIs, making them easily filterable and accessible.

What is an "Aspect API"?

An Aspect API is an API that delivers data corresponding to an Aspect Model — the semantic model that describes the meaning of the data.

Prerequisites

To create an API for consuming your semantically described data, you must provide related information and artifacts, select user roles, and optionally specify details for Asset Administration Shell use cases.

Overview

You must provide:

The URN for the Aspect Model that describes your data
Learn more: SAMM specification > About Aspect Models and URNs
An SQL schema file that corresponds to the Aspect Model
A YAML file that defines custom mappings where necessary

To define API access, you will be asked to select:

The required user role for accessing your API
The attribute-based access control (ABAC) rule
With that, only users that have the selected roles will be able to access your Aspect API.

If needed for your API’s use case, you can also specify (optional):

The related Submodel Descriptor Template URL for the Aspect Model
Related Asset Administration Shell groups
With that, the API generator gives you the option to adapt the resulting API URL, so that it can be consumed by Asset Administration Shell users as if they would consume a Submodel Descriptor.

Further details

SQL schema file

You must provide an SQL schema file.

Example schema file content:

create TABLE movement_view (tenant_id TEXT, is_moving BOOLEAN, latitude DOUBLE, longitude DOUBLE, altitude DOUBLE, speed DOUBLE, speed_limit_warning TEXT );

YAML custom mappings file

You must provide a YAML custom mappings file.

By doing it, you can map column names from the SQL table to Aspect Properties, especially when the names are not the same. Additionally, custom mapping allows you to exclude Aspect Properties from the SQL table columns.

Example mappings:

mappings:
  - aspectModelPropertyName: streetName
    ignore: true
  - aspectModelPropertyName: houseNumber
    ignore: true

If for your API no mappings between SQL schema and Aspect Model Properties are needed, upload a YAML file with only the following content:

No custom mappings needed:

mappings: [ ]

How to proceed

To create an Aspect API, ensure you have met the Prerequisites.

Proceed as follows:

Go to your tenant’s workspace.
In your workspace, navigate to Aspect on Demand.
On the upper ribbon, click the Create New Aspect API button .
→ A dialog opens, prompting you to fill in different types of data required for the generation of your Aspect API.
Follow the steps as indicated by the dialog.
- Step Access and Security: Note that "MACMA" stands for Multitenant Access Control Management Application and refers to user roles that you can define for your tenant using Access Management.
  Learn more about Access Management: Add a module to your tenant
- Step Digital Twin Integration: To create a valid URL for Asset Administration Shell users, check the Asset Administration Shell enabled checkbox and provide a Submodel Descriptor Template URL.
Review your inputs at the last step. If everything is correct, click Create.
→ The generation process for your API starts. Your API already appears in the Aspect on Demand API overview. In the beginning, it has the status Upgrading which indicates that the generation process is running.

During the generation process, the status for your API changes:

From Upgrading
To Provisioning
To Success

If an error occurs during the generation process, the process stops and your API status is Failed.

Troubleshooting

If you have met the Prerequisites correctly and the generation process for your API still ends with status Failed, contact our support team.

Search and filter your Aspect APIs

On the in the Aspect on Demand API overview, find all Aspect APIs you have generated.

You can search for them by the name of the Aspect Models, their definition, version, and API version. Use the Search field to do it.

Filtering is available through the update date and status of the Aspect API and can be performed via the respective dropdowns, situated on the upper ribbon.

Sorting can be performed alphabetically or by Aspect Model, its definition, version, or Aspect on Demand version. Use the dropdown on the upper ribbon.