Many customers want to start the day with an historical query (last 24 hours, or last 48 hours), and then get incremental updates, perhaps every 5 or 10 minutes, over a long period of time. The REST API includes server-side features that make it easy to achieve this kind of data feed behavior.
You can use this method to build a live feed dashboard, or doing near-real-time analysis on test results, perhaps to track site availability or average response time. You don't want to have to query 24 hours' worth of data every 5 minutes (and we don't want you to).
The workflow for the an incremental data feed pattern of requests will follow this basic pattern (specific options used in your particular case will vary):
- Retrieve a bearer token with a request to the Login resource. All interaction with the REST API starts with this step.
- Create a request for the Test Results resource.
- Select the start and end dates/times for the interval you want. You can optionally specify just the start date/time, and let the end date/time default to now, but remember that the maximum size of the resulting time interval is 48 hours.
- To ensure that you don't miss data from one request to the next, you must set the
ARRIVAL(or leave this parameter out, as
ARRIVALis the default).
- Execute the request.
- Wait at least one minute. This is the minimum time required between requests to the Test Results resource.
- Execute the same Test Results request again, except this time omit both the
- Repeat steps 4 and 5 as necessary.
The cached user context contains (among other things) the
end time parameter of your previous Test Results request. When you execute your incremental request, the server automatically finds your previous
end parameter and uses that as the
start time for your new request (the new request's end time defaults to now). As a result, you receive the data that is newly arrived in the database for the specified tests since the last time you sent a request.
Your user context is cached per-bearer token. This means that if you use a given User ID to log in on more than one device, you can still reliably use the data feed pattern to obtain incremental data on both devices and the server will not be confused about what each device wants.
The REST API servers do not cache the user context forever, periodically flushing user context data. Naturally, this will cause incremental data feeds requests to break. When this happens, you'll execute an incremental request, and receive a
400 status error with a response body containing a message similar to the following:
Invalid input arguments, need both start and end for new feed query.
If you encounter this error, you can recover simply by re-starting your incremental data feed pattern.