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 the operator 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