Sending a Heartbeat

Once a client application has made a successful access request in a session, it must send a regular heartbeat to the session to confirm that the client is still using the items. The application must do this using a GET to the /api/v1.0/sessions/{sessionID}/heartbeat endpoint. Elastic Access must receive a heartbeat within 30 minutes of the last automatic charge made by the session.

The client must read the response to the heartbeat. If the response is a status 204, the client can continue using the application. If any other status is returned, the client should not continue using the application and ought to close it.

Note that the client application is not required to send a heartbeat after the initial charge. However, it must send a heartbeat after each automatically repeated charge to keep the session going. The application should not send heartbeats more frequently than required.

If Elastic Access does not receive a heartbeat within 30 minutes of the last automatic charge, it assumes that the client is no longer using the most recently requested items and that the most recent automatic charge was made in error. Hence Elastic Access does the following:

• Refunds tokens charged in the last automatic charge.
• Sets the session to a TERMINATED state.
• No longer accepts access requests for the session.

If the client wants to start using an application or items again, it must restart the process by creating a new session and requesting items.

For more information about automatic charges, see Automatic Charging Concepts.

Session Example Showing Heartbeat

The following sequence lists the events that occur when a client application requests an item as part of a session:

1. 0 minutes: Start of timeline. The client application requests items. Elastic Access makes charge 1 and sends usage information to the data warehouse.
2. 60 minutes: Automatic charge 2 is made after one hour. Usage information is sent to the data warehouse.
3. Within 30 minutes of automatic charge 2: The client application sends a heartbeat.
4. 120 minutes: Automatic charge 3 is made. Usage information is sent to the data warehouse.
5. 150 minutes: 30 minutes have passed since the last automatic charge (charge 3), without Elastic Access receiving a heartbeat from the application. Elastic Access assumes that the client has shut down the application and is no longer using it. Elastic Access therefore does the following:
• Ends the session. The session accepts no more access requests and its state changes to TERMINATED.
• Issues a refund for the entire automatic charge 3 made at 120 minutes and sends this information to the data warehouse.