Understanding the xAPI Specification: State API

07 July 2016 by Ryan Smith

We’ve already looked at the Statement API, but the xAPI Specification also gives room for three other APIs that aren’t statements: the State API, the Activity Profile API and the Agent Profile API.

In this post, we take a look at the Activity State API (commonly referred to as the State API), and how to use an API querying tool such as Postman, to query it.

What is the State API?

The State API component of the xAPI allows you to associate the relationship between a user and an activity in a given ‘state’ such as a user progressing through a course, e.g. User X is on level 4 in Tetris.

The xAPI specification states that “generally, this is a scratch area for Activity Providers that do not have their own internal storage, or need to persist state across devices”.

Querying the State API

Now you know what the State API is, we’ll take a look at querying it. If you’re not familiar with Postman, you may find it useful to watch this video walkthrough to better understand how to set the query:

Creating a State

To create a state, you can use a request similar to the one demonstrated below.

POST https://v2.learninglocker.net/v1/data/xAPI/actvities/state

URL Parameters

activityId:https://www.example.com/activities/1

stateId:https://www.example.com/states/1

agent:{“objectType”: “Agent”, “name”: “John Smith”, “account”:{“name”: “123”, “homePage”: “https://www.example.com/users/”}}

Headers

Authorization:Basic YOUR_BASIC_AUTH

X-Experience-API-Version:1.0.0

Content-Type:application/json

Body

{

“favourite”: “It’s a Wonderful Life”,

“cheesiest”: “Mars Attacks”

}

Retrieving a State

To get a given state for a user in an activity, you can use the State API as demonstrated below. You may create the state on one device (e.g. a laptop), and retrieve the state on another (e.g. a phone), then redirect the user to a certain part of an activity (e.g. question 5 in a quiz), so that the user can continue from where they finished on another device.

GET https://v2.learninglocker.net/v1/data/xAPI/actvities/state

URL Parameters

activityId:https://www.example.com/activities/1

stateId:https://www.example.com/states/1

agent:{“objectType”: “Agent”, “name”: “John Smith”, “account”:{“name”: “123”, “homePage”: “https://www.example.com/users/”}}

Headers

Authorization:Basic YOUR_BASIC_AUTH

X-Experience-API-Version:1.0.0

Response

{

“favourite”: “It’s a Wonderful Life”,

“cheesiest”: “Mars Attacks”

}

Retrieving All States

You may want to retrieve all of the states a user has been through in a activity. The request below demonstrates how that can be done via the State API.

GET https://v2.learninglocker.net/v1/data/xAPI/actvities/state

URL Parameters

activityId:https://www.example.com/activities/1

agent:{“objectType”: “Agent”, “name”: “John Smith”, “account”:{“name”: “123”, “homePage”: “https://www.example.com/users/”}}

Headers

Authorization:Basic YOUR_BASIC_AUTH

X-Experience-API-Version:1.0.0

Response

[

“https://www.example.com/states/1”

]

Deleting a State

Finally, you may want to forget about the state or remove an incorrect state. This can be achieved with State API as demonstrated in the request below.

DELETE https://v2.learninglocker.net/v1/data/xAPI/actvities/state

URL Parameters

activityId:https://www.example.com/activities/1

stateId:https://www.example.com/states/1

agent:{“objectType”: “Agent”, “name”: “John Smith”, “account”:{“name”: “123”, “homePage”: “https://www.example.com/users/”}}

Headers

Authorization:Basic YOUR_BASIC_AUTH

X-Experience-API-Version:1.0.0

Additional Aspects of the State API

The State API isn’t for analytics so much as it is about understanding a user’s position in some activity at a later state.  There are also other bits to the API that we’ve not covered here which we recommend you read up about in the spec if you’re interested in finding out more about.

Next up, we’ll be looking at the Agent Profile API

For more practical xAPI advice and support, download our free Technology Manager’s Guide to xAPI

blank
Ryan Smith
Software Development Team Lead

Starting as a placement student in 2014, Ryan re-joined the Learning Locker team after graduating from Oxford Brookes University where he won the John Birch prize for the highest grade average in the University.

From his minimalist desk, Ryan leads the Learning Locker team and consults with people on all things xAPI to conscientiously craft products and services that sustain and evolve training and performance.

When he’s not swimming or injuring himself on the cricket field, Ryan enjoys playing funny (and usually inappropriate) games with his family.

View more from Ryan Smith
blank
Read more about Learning Pool
Visit our Learn and Connect section

Get a free demo

Get in touch to find out how we can help

Start your learning journey

Get started by telling us what you need and one of our team will be in touch very soon.