Composite API
A composite API is a sequence of tasks that runs synchronously and whose execution path is not persisted.
Definition
Composite APIs are best described by comparing them with processes :
- Both processes and composite APIS are a sequence of tasks.
- Composite APIs run synchronously unlike processes : the result of triggering of a Composite API is the result of the execution, not the request that will contain the result of the execution once it is finished.
- Each composite API can be triggered by calling its API.
- A composite API execution is never paused, which implies that a composite API cannot contain manual tasks nor subprocesses tasks unlike a process.
- A composite API execution path is not persisted unlike a process which enables it to run more quickly.
When you are about to decide whether to use a Composite API or a process, take into account the existing Execution Limits.
Triggering a Composite API
A composite API can be triggered in the following ways:
- As a task in a process.
- As a listener in a web interface.
- Directly via its exposed API (from a third-party).
Use cases
A composite API may be used :
- To speed up the execution of a sequence of tasks.
- To improve listeners performance in web interfaces.
- To compose an API by creating a sequence of web services calls that is meaningful.
Design
The design of a composite API includes the design of the sequence of tasks like in a process and the design of its exposed API.
Contrary to a process, the corresponding REST API of a Composite API can be configured. You can configure :
- The
Method
: the HTTP verb. - The
Accept media type
: the media type of the input. - The
Result media type
: the media type of the output.
It is important to note that a Composite API which is triggered from a web interface must be configured with its Accept media type
set to application/json
.
A good practice is to choose the HTTP verb that matches what the composite API does :
- GET if it only retrieves information
- PUT if it modifies something
- POST if it creates something
- DELETE it it deletes something
Debugging and Maintenance
Since the composite API execution path is not persisted, the test and debug should be thought very differently from what is done with processes.
Retrieving the error
An unhandled error launched during the execution of a Composite API will appear in the customer logs which have been introduced with the mogador
release. They can be accessed in the Logs Application.
When the execution of a composite API fails, the error is logged in the Custom Logs
with the following information :
- Date : Date and time of the error
- Log Level : An unhandled error that aborts the execution of a Composite API will always be
SEVERE
- Message : The error message
- Process ID / Composite API ID : ID of the Composite API
- Project ID : ID of the context project. For a composite API belonging to a project B, subproject of a project A, that is launched by a process or a web interface from project A, the context project will be project A.
- Request ID : Unique ID of the Composite API execution.
In addition and depending on how the Composite API was launched, the error message can also be retrieved in the execution context
- Composite API launched from a process : The error message is returned to the request
P_message
variable. - Composite API launched from a web interface : The error message is returned in a
P_error
variable.
Throwing your own errors
The platform provides a freemarker method throw
that enables you to throw an error and abort the execution of the Composite API.
This method enables you to define a error message, that will be returned into the execution context as seen above.
Handle errors
Composite API can handle errors exactly in the same way as process by using error handlers in their design. Error handlers enable you to capture errors and deal with them.
Errors you should always expect and handle are timeout and rate limit errors. For details, refer to the existing Execution Limits.
Debugging
The Logs Application can also be used to track the execution of composite API by using the P_log
function within the composite API.
This method can be quite useful for debugging.
(@see Composite API Example)
Please give details of the problem