How does the Results API work?

The Results API OData feeds are designed to return specific datum and granular subsets of data. When querying multiple data in a feed, querying multiple feeds simultaneously, or querying against the content in a variable that is not a key field for the feed, the Results API may timeout. Users are encouraged to design queries to use specific key values.

To introduce you to our Results API if you are unfamiliar with OData services, let's start off with an example—accessing the Participants feed and retrieving a list of participants.

Perception users would enter the following HTTP request in a browser:

https://<server name>/analyticsodata/<tenant ID>/odata/Participants

...where <server name> is the fully-qualified name (including the domain name) of the server where Perception is installed and <tenant ID> is the name of the specific Perception repository are you trying to access the result data for.

OnDemand user would enter the following HTTP request in a browser:

https://ondemand.questionmark.com/<customer ID>/odata/Participants

...where <customer ID> is the customer ID of the OnDemand account you want to access the result data for.

This example is for an OnDemand user, but a Perception user would follow the exact same steps using the Perception-specific URL format shown above. After authenticating (see the How can I access the Results API? section for details), this will retrieve a list of all the participants who have created results that have been ETLed into your Results Warehouse at the time you are accessing the Results API. If you have more than 500 participants in your Results Warehouse, at the bottom of the page you will see a link that looks similar to the following:

<link rel="next" href="https://ondemand.questionmark.com/<customer ID>/odata/Participants/?$skiptoken=500" />

If you wanted to view participants 501 and on, you would enter the address from the  href= part of the above <link rel> entry to navigate to the second page of participants.

A list of participants from the Participants feed includes entries for each participant in the list. Here is an example entry for a single participant:

<entry xml:base="https://ondemand.questionmark.com/123456/odata/" xmlns:d="http://schemas.microsoft.com/ado/2804/08/dataservices" 
xmlns:m="http://schemas.microsoft.com/ado/2804/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom">

Each participant entry includes an ID, which is a URL that allows you to return to this particular entry at any time without having to retrieve the entire list of participants, which can be quite lengthy. The above example's ID, as you can see from the <id> tag, is:

<id>https://ondemand.questionmark.com/123456/odata/Participants(804)</id>

A participant entry not only returns information about a particular participant, but it may also include navigation links, which are links to related Results API entries from other feeds. The above example includes three navigation links, which are identified by <link rel> tags. The first navigation link in an entry will always be a link to itself and the ones after links to entries from other feeds. In this example, the second navigation link is a link to all the results for this participant:

<link rel="http://schemas.microsoft.com/ado/2804/08/dataservices/related/Results" type="application/atom+xml;type=feed" title="Results"href="Participants(804)/Results" />

To navigate to the list of results for this participant, you would append the address in the href= section of the navigation link to the participant entry's URL, which would look like the following:

https://ondemand.questionmark.com/123456/odata/Participants(804)/Results

The list of results that the above URL would retrieve would include all the assessment results that have been ETLed into the Results Warehouse for this participant. From there, you could use other navigation links to visit other related entries. Because all the Results API links are internally linked to each other, you could literally go on forever, jumping from related data to related data.