Composite APIs

A composite API (CAPI) is a sequence of steps that is executed synchronously on the platform within a short time without user interaction and interruption.

Composite APIs are similar to processes but faster as their execution path is not persisted. For this reason, they can be used to speed up the execution of task sequences and improve the performance of listeners in web interfaces. Composite APIs are also suitable to implement business logic that is to be accessible by REST API calls, and to compose APIs as sequences of web service calls. They can be used, for example, to retrieve data from external systems, generate items like PDF files or objects in collections, or export data to CSV or other formats.

A composite API is designed in the same way as a process with the same types of steps. It may involve other composite APIs or connectors to perform its activities, but not invoke subprocesses or web interfaces.

In addition to the design, the configuration of a composite API comprises the definition of its exposed interface. Composite APIs can be triggered by direct web service calls to this interface, by timer or email events, or from processes or web interfaces.

The design and configuration of a composite API comprises the following settings and considerations, which are described in detail in the sections below:

Composite API Identification

The following settings identify a composite API in DigitalSuite:

Name: The name of the composite API, also referred to as the title.

It is recommended that the names have CAPI - as their prefix, for example, CAPI - Get Dictionary.
ID: A generated number used to uniquely identify the composite API.

Interface Definition

Composite APIs must expose a REST interface by which they can be invoked. The interface definition consists of the following elements:

URL: The URL to address the composite API.

Technically, a composite API is a connector (web service) provided by the RunMyProcess Server provider. Therefore, the URL consists of a provider (root-endpoint) and a connector (path) part. Both are generated automatically and cannot be changed. For example:

Provider URL: https://live.runmyprocess.com/
Connector URL: live/620821136/host/61617/service/296524?P_version=${P_version}&P_mode=${P_mode}
Architecture: The protocol used to work with the composite API: REST/XML-RPC.
Method: The HTTP request method for the action performed by the composite API:

GET for retrieving items
POST for creating items
PUT for modifying items
DELETE for deleting items
Accept media type: The type of content the composite API accepts from a web service call (Accept request header). DigitalSuite supports different media types. application/json should be chosen if the composite API is to be used as a listener in a web interface.
Input validation: A FreeMarker script to check if the data (body) passed in the web service call fulfills specific criteria, for example, if parameters required by the composite API have been specified. If this is not the case, an error message is returned and the composite API is not executed.
Result media type: The type of content the composite API sends in its response. DigitalSuite supports various types. application/json should be chosen if the composite API is to be used as a listener in a web interface.
Result transformation: A FreeMarker script that provides the response of the Composite API in the format specified by the result media type.
Description: A description of the composite API and its exposed interface, including all the input and output data and parameters.

Step Design

Composite APIs are designed as a series of steps in the same way as processes. They support the same step types (events, activities, gateways) except for:

Subprocess activities
Manual activities

For details, refer to Process Steps and Process Step Types.

Since composite APIs need to be simple and fast, they should avoid to use:

Concurrent execution paths (AND splits and joins)
More than 5 loops
Back loops
More than 20 connectors

Variables

Like processes, composite APIs and their steps typically require some input and produce some output. These are managed and transferred by means of input and output variables. A composite API can have multiple:

Input variables: Parameters and data that are required to launch the composite API. These are passed in the web service call as defined by the composite API.
Step variables: Input and output variables of activities and events. For more details, refer to Process Step Variables.

Unlike processes, composite APIs do not support measures.

Accessibility

Access to a composite API can be set to public or private. Public composite APIs can be called from web pages and services without verification while users need to authenticate and have the required permissions to invoke a private composite API.

Like for processes, the design of a composite API can have multiple pools and lanes reflecting organizations and roles for access control. However, since a composite API does not involve manual tasks to be carried out by users with different roles, all the steps are usually executed within a single lane specifying the role whose members are allowed to start the composite API.

Triggers

A composite API can be triggered in the following ways:

By an event or activity in a process or another composite API. For details, refer to Process Step Types.
From a widget or a listener configured for a web interface. For details, refer to Web Interfaces.
By an email sent to an auto-generated email address. To this end, the start event of the composite API must be a Message Start Event.
By a timer that is triggered at a defined frequency. To this end, the start event of the composite API must be a Timer Start Event.
From a provider configured with the OAuth v2 authentication scheme. In this case, the composite API is used for OAuth 2.0 customization according to an application's requirements.
Directly by web service calls to its exposed API, for example, from third-party systems.

Composite APIs versus Processes

Composite APIs and processes are both sequences of steps and similar in many aspects. The decisive differences are the following:

Composite APIs are executed synchronously without pause or interruption. For this reason, they cannot contain manual tasks and subprocesses.
The execution path of a composite API is not persisted, while each execution of a process creates and stores a corresponding instance (process request).
The result of triggering a composite API is the API's direct response. The result of triggering a process is a process request, which is executed asynchronously and contains the result once it is finished.

These differences make composite APIs run faster than processes, but more difficult to monitor.

Designers should consider the usage of composite APIs instead of processes when they need to:

Speed up the execution of a sequence of tasks.
Improve the performance of listeners in web interfaces.
Compose an API as a sequence of web service calls.
Trigger processes using JSON instead of XML for easier handling or communication with external web services based on REST.

A decision on whether to use a composite API or a process should always take into account the relevant execution limits.