Long-Running Operations Through REST
This document describes Long-running operations that follow RESTful principles.
What is a Long-Running Operation?
A long-running operation is a business operation that takes a long time to complete. If the operation lasts for a duration that is enough to make a user or an application wait for results, then it is a long-running operation.
The actual business operation is asynchronous from the initial request. The processing continues regardless of the operation returning a response.
Asynchronous Processing and RESTFul Principles
The RESTFul principles help Oracle Health Insurance to:
-
Expose a business-specific resource for each long-running business operation.
-
Leverage HTTP response codes and hypermedia links to track and control a business operation.
HTTP Response Codes and Hypermedia Links
Every long-running operation follows the steps below:
-
A user or an application performs an HTTP POST to a resource.
-
The Oracle Health Insurance application responds with HTTP 201 (Created) and a location header for the long-running operation.
From there, there are several choices to track the progress of a long-running operation:
-
Notification events,
-
Search for a long-running operation from the collection of long-running operations, or
-
Interact with the application
Leveraging Notification Events
The application sends a notification event once a long-running operation reaches an end state. Notification events are call-backs for a user or an application to resume the flow of operation.
Notification events must carry the right amount of information for a call-back to make sense. The hypermedia links help with this.
Following are the links per long-running operation:
-
operator:subject
A hypermedia link with
rel="operator:subject"
. The address refers to the long-running operation resource. The call-back system uses this link to gain information about the notification event. This link informs about the operator (see the "Interrogating the Operator" section below for more information). -
datafileset
A hypermedia link with
rel="datafileset"
. The address refers to the link for the data file set that results from a long-running operation. This link is present only when the long-running operation is successfully completed. -
It is possible to have more links depending on the operation.
- Sample Notification Structure
<notification correlationId="" workId="" status=""> <links> <link rel="file" href="{apiurl}/datafilesets/\{datafilesetcode}/datafiles/\{datafilecode}/data"/> <link rel="file" href="{apiurl}/datafilesets/\{datafilesetcode}/datafiles/\{datafilecode}/data"/> ... </links> <fields> <key1>value1</key1> <key2>value2</key2> </fields> </notification>
-
workId: ID of the invoking process. For activities, this is the
activityId
. -
correlationId: The correlation ID for the operation.
-
status: Success or failure for a process, like activity processing. If the activity is complete, the status is success. Else, Failure.
-
links: For links explained above and operation-specific links like
ref= file
for data files. A user can follow this link to download data files. -
fields: Key and value pairs of data for each notification.
Leveraging Ad Hoc Collection Query Capabilities
As long-running operation resources apply standard HTTP APIs techniques, it is possible to perform regular collection queries. This is helpful to check the status of a long-running import process - at some point later in time - for an audit.
The response has the following links depending on the status of the long-running operation:
-
monitor
A hypermedia link with
rel="monitor"
. The address refers to the long-running operation resource. For more details, check the "Leveraging Interactive Monitoring of Progress" section. -
operator
A hypermedia link with
rel="operator"
. The address refers to the (technical) operator that executes the long-running operation. Follow this link to gain more information about the operator. For example, to see problems encountered during processing the request or to restart a failed operation.
Leveraging Interactive Monitoring of Progress
Tracking the progress of a long-running operation is possible by interacting with the application - through a location header.
A use case for this is when the input parameters constraint a targeted export of some Oracle Health Insurance data (for example, ReadConsumptionBatch
) that results in a small result data set.
This pseudo-blocking of asynchronous execution is called Polling.
A user or an application can implement a polling behavior using the tracking link in the Location header. The link becomes available after the success of the first submission process.
A GET operation on the header contains the following links:
-
monitor
A hypermedia link with
rel="monitor"
. The address refers to the long-running operation resource. It shows that theoperator
that executes the long-running operation is yet to reach its end state. A user can use this information to implement a polling behavior.
The absence of the rel="monitor"
link shows the operation has reached an end state.
In that case, a response entity can hold the following links:
-
operator
A hypermedia link with
rel="operator"
. The address refers to the (technical) operator to execute the long-running operation. Follow this link to gain more information about the operator. -
datafileset
A hypermedia link with
rel="datafileset"
where the address refers to the result of the long-running operation.
Interrogating the Operator
A user or an application can interact with rel="operator"
present in the response of a long-running operation.
-
To obtain more information about the messages that the operator registers during the execution of the long-running operation. A user or an application can obtain messages with the
rel="operator:messages"
link if it is present in the response entity. -
To restart a failed operator. A user or an application can restart a long-running operation with a problem after resolving the cause of the problem. A
rel="operator:restart"
must be present in the operator response entity to restart the operation.
Examples
-
A Complete Example - ReadConsumptionBatch uses the Data File Set.