Understanding the xAPI Specification: State API

In previous blogs, 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’ll 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.