Generate and deploy an API

For your data — as contained in the Semantic Data Lakehouse — generate custom APIs ("Aspect APIs") to consume that data.

What is an Aspect API?

An Aspect API is an API that delivers data corresponding to an Aspect Model. An Aspect Model is 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.

Prerequisites overview

Key prerequisites

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
For further details, see below: SQL schema file
A YAML file that defines custom mappings where necessary
For further details, see below: YAML custom mappings file

Defined user roles

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

The required user role for accessing your API
Find available roles for Aspect on Demand listed at Access and permissions
The attribute-based access control (ABAC) rule

With that, only users that have the selected roles will be able to access your Aspect API.

Optional details for Asset Administration Shell use cases

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 are available for your tenant.
  - For more information on MACMA and tenant management, refer to Multitenant Access Control.
  - For an overview of available user roles for Aspect on Demand, refer to Access and permissions
- 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.

After successful generation, your API is deployed and ready to be consumed. Learn more: Consume a generated API

Troubleshooting

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