Composite API Concepts
Composite APIs fulfil the need for synchronous actions which are performed server-side, for example, retrieving live data from a third-party system or creating/generating objects, such as an item in a collection, a PDF file, or a CSV export.
Processes are an alternative for performing such actions. You can design a process and call corresponding activities from the process itself using, for example, a subprocess, or directly from a web interface as a process listener. Keep in mind, however, that the process execution runs asynchronously. This means that it generates a high load on the DigitalSuite platform and takes long to get the result.
As a hybrid solution between processes and connectors, a composite API has the following characteristics:
- Like a process, a composite API describes a sequence of activities.
- A composite API cannot contain a manual task or a subprocess.
- A composite API can be triggered by calling its API (connector).
- Executing a composite API is different from executing a process: The result of triggering a composite API is the direct result of its execution. The result of triggering a process is the request that contains the result of the execution once it is finished.
- The execution of a composite API is never paused.
- A composite API's execution path is not persisted. This makes it run faster, but more difficult to monitor.
You should consider using a composite API when you want to:
- Speed up the execution of a sequence of tasks.
- Improve the performance of listeners in web interfaces.
- Compose an API by creating a meaningful sequence of web service calls.
- Allow triggering processes encoded in JSON format instead of XML, as composite APIs use the REST protocol which enables the communication with external web services based on REST. Another advantage is that JSON content is easier to handle than XML content.
For the decision whether to use a composite API or a process, take into account the execution limits. For details, refer to Execution Limits.
Configuration and Design
When creating a composite API, you define its name, the role that is authorized to trigger it, and the settings of its exposed API. This configuration is similar to the configuration of a connector. The default provider of a composite API is
RunMyProcessServer. The provider URL and connector URL of the composite API are generated automatically.
A composite API describes a sequence of activities that take place during its execution. When designing a composite API, you can use the types of activity you also use for designing a process, except for manual tasks and subprocesses. The activities and elements used in composite API design are a subset of those for processes. For details, refer to ProcessModeler.
A composite API can be triggered:
- By an email sent to an auto-generated email address. The event that starts the composite API is of type Message Start Event. For details, refer to Step Types.
- By a timer that is automatically triggered at a defined frequency. The event that starts the composite API is of type Timer Start Event. For details, refer to Step Types.
- By an activity in a process. The activity is of type Connector Activity. For details, refer to Step Types.
- By configuring a listener that triggers the composite API upon a specified event in a web interface. For details, refer to WebModeler Concepts.
- Directly via its exposed API from the third-party software that is involved.