API Manager

The menu item API Manager appears in the Integration menu node in a session referring to a role (see Roles) with sufficient permissions.

Clicking the menu item opens an overview for the entity type 'API' (RestApiDefinition).

View name: de.lobster.scm.api::RestApiDefinition|listSearchWindow
Menu node name: integrationModules/restApi

Access to 'API' entities is controlled by the permission node 'Administration/Configuration/(REST/MCP API)' (administration/designer/restApiDefinition).

The menu item API Manager will only appear in the menu if the Role of session has permission to 'Show' (show) it.
Generally, owner restrictions apply for 'API' entities with respect to the Company of session.
Permissions for the Role of session are therefore only applicable to 'API' entities, which the Company of session owns or receives corresponding Company authorizations for.

Instances of entity type 'API' (RestApiDefinition) define REST interfaces for the Lobster Data Platform server.

The 'API' instance is a mere outer shell for managing the API definition embedded via its 'API' (api) property.

This API definition is an instance of one of the following REST API classes:

REST API (RestApi): Defines endpoints (for calling HTTP methods) for general REST requests.
MCP Server (McpRestApi): Defines tools for requests by Artificial Intelligence (AI) via the Model Context Protocol (MCP).

Regardless of the API definition type, access to details of a discrete 'API' instance relies on the same predefined input form (see Input forms). However, the effective appearance of the form varies per API definition type selected or given.

The input form is opened by view name de.lobster.scm.api::RestApiDefinition|detailsWindow if sufficient permissions are granted.

Typically, the input form is accessed from the overview opened by menu item API Manager.

Clicking on the ribbon button 'New' (in the overview) opens a context menu to poll a choice for API definition type from the user.
IMPORTANT There is no interactive method to alter this choice for an existing 'API' instance later on. Typically, this initial choice will persist throughout the full life cycle of an 'API' instance.
- The ribbon button 'New' appears only if the Role of session is granted the 'Create' (create) permission for the entity type.
- The API definition type selected from the context menu for the new instance, determines the appearance of the opened input form.
With exactly one selected 'API' instance selected, double clicking or clicking the ribbon button 'Edit' or 'Show details' will open the input form with the data of that instance.
- The ribbon button 'Edit' appears only if the Role of session is granted permission to 'Update' (update) the instance.
- The same ribbon button appears with the alternative caption 'Show details', if the Role of session is only granted the 'Show' (show) permission and/or 'Create' (create). Even then, the volatile data of the entity may be edited in the opened input form. However,
  the ribbon button 'Save' appears disabled, in this case. If 'Create' (create) is permitted, the ribbon button 'Copy' can be used to transfer the volatile data to a new 'API' instance, which can then be saved.

Configuration

The following sections describe configuration properties of entity type 'API' (RestApiDefinition), which apply for all API definition types.

Each section refers to an individual tab in the input form.

NOTE Details featured in individual tabs per API definition type (tabs 'API' and 'Meta information') are described in the articles REST API or MCP Server, respectively.

Basic settings

Property	Data field	Data type	Description
Enabled	`enabled`	`Boolean`	The 'Enabled' flag controls whether the complete 'API' instance is defined as an operative (`true`) or not (`false`). By default, this flag is not set. A newly created 'API' must be activated, to effectively accept requests. NOTE Updates to the activation status only become effective when the 'API' instance is saved. Changing the activation status of an individual 'API' may or may not render immediate operative effects, due to overlaps between endpoint/tool definitions distributed across multiple 'API' instances, if these belong to the same 'Base URI' (see below: 'Priority').
Owner	`ownerId`	`Long`	Unless specified otherwise, the Company of session is assigned as an owner when an ‘API’ instance is created (saved for the first time). Alternative choices (if any) are featured in a Combobox element for the input form. Owner-restrictions are only relevant with respect to the configuration of an ‘API’ instance. Ownership and Company authorizations have no immediate influence on runtime access to an API.
Name	`name`	`String`	Each ‘API’ instance must be assigned a ‘Name’. Since an entity is internally identified by an ‘ID’ (`id`) automatically assigned by the system, the assigned ‘Name’ is not required to be unique. Its purpose is to provide orientation while managing configurations, but it has no relevance for interface operations.
Description	`description`	`String`	The Text field ‘Description’ can be used optionally to provide informative multi-line text. Typically, this provides documentation for the purpose of a configuration and/or changes applied to it. This property has no relevance for interface operations. NOTE Besides defining a 'Description', it is also possible to categorize an 'API' instance by assigning Tags. This may be especially useful in the context of managing transfers of such configurations between systems via Meta exchange.
Priority	`priority`	`Integer`	The 'Priority' property can be set to a positive or negative integer value, which may influence the priority of 'API' instances with API definitions linked to the same context (by Base URI and tool or endpoint properties). In case of ambiguity regarding an incoming request, the applicable tool or endpoint definition linked to the 'API' instance with the highest 'Priority' value handles the request. NOTE A disabled 'API' instance (see above: 'Enabled') is not even considered a candidate for handling requests. The priority of a disabled instance is therefore irrelevant. A disabled 'API' instance with high priority will not 'intercept' and effectively neutralize request to its tools or endpoints.

Private structures

The 'Private structures' tab can be used to define private client object structures. These define custom data structures that can be referred to in configurations related to the 'API' instance by their assigned 'Alias' (see Client object structure reference). They are called private as their use is limited exclusively to the context of the parent 'API' instance.

The definition of a data structure relies on a list of properties that may or must be featured in a client object, to make it match with the 'private type'.

The following screenshot shows an example where two private structures (Waypoint and Leg) are defined for the context of the same 'API' instance:

The 'Private structure' with Alias Waypoint defines a waypoint for an air connection.
The location property expects a text value (String) identifying the waypoint.
The locationType property may optionally provide another text value (String) to indicate that the text provided for the location property is a code from a certain context.
- The Check box Optional (see Popover in screenshot) is selected, which makes the property optional. In the list of 'Fields' a ? appears as a suffix to the property name (locationType).
- A String values validator (Client object structure) has been added to the field definition, which specifies a whitelist for accepted locationType text values (here: ICAO, IATA).

The second 'Private structure' with Alias Leg demonstrates another use case for 'Private structures', as it contains multiple references to the first 'Private structure' as the data type for its properties.
The Leg structure combines two or three Waypoint instances to describe an air connection from fromWaypoint to toWaypoint with the option to specify a viaWaypoint as a stopover.

Within workflow configurations for an endpoint or a tool of the parent 'API' definition, a Check client object structure rule or the Check client object structure (Resolver) might be used with a reference to one of these structures to validate input values.

On the other hand, a 'Private structure' could also be referred to from a Create instance with values resolver to facilitate the assigning of values to client object properties for a return value (Variable response):

NOTE In this example, the 'Private structure' Waypoint is only referenced as a Client object structure for the 'Client object' instance to be created, to populate the dropdown for the Property choice as a target for assigning values. This does not enforce a type check for assigned values (here: ICAO) involving the String values validator (Client object structure) defined for the locationType property. However, a Check client object structure (Resolver) chained below would enforce a type check.

Private subroutines

The 'Private subroutines' tab allows the definition of Custom subroutines (follow link for details). These are called private, as they can be addressed exclusively from the context of the parent 'API' instance.

'Private subroutines' may be Event actions, Resolvers or Rule types with a specific characteristic tailored and limited to the context of the 'API' instance.