For storing (and sharing) state!
Last time we dived into the Document APIs as a whole. This time we dive deeper into the most well known and commonly used of the Document APIs, the State API. As there’s a lot of similarity between the State API and Activity Profile API (and I don’t have a whole blog worth of content on the State API alone) we’ll cover the Activity Profile API too.
The State and Activity Profile APIs provide a place for Activity Providers that have no storage of their own to store Documents. These APIs are no substitute for an Activity Provider’s own storage, and if you can use your own data store instead, you should. They are useful for small tools for which their own database would be overkill, for converted legacy SCORM content (which would previously have stored data with the LMS), and for new SCORM style content. They can also be useful for communication between a Training Delivery System such as an LMS and the Activity Provider.
The State API
Within the State API Documents can be stored on two different levels. First, data can be stored on a per user, per activity basis. Common uses include high scores or bookmarking data. Next, data can be on a per registration, per user, per activity basis. This is used for data specific to a particular launch or attempt. The Activity Provider is responsible for cleaning up after itself and deleting old state documents which are no longer required.
The Activity Profile API
The Activity Profile API is used to store activity wide documents that aren’t specific to an individual learner. This is used in any scenario where interaction between learners is required, for example collaboration activities, social interaction or competition.
Also included in the Activity Profile API is access to the LRS canonical definition of a given Activity. This is retrieved via a Full Activity Object GET request. The Activity Definition can be built up based on the definitions of the Activity given in Statements sent to the Statement API, can be provided in metadata hosted at the location specified by the Activity ID’s IRI or can come from another source used by the LRS. This is a read-only resource and can’t directly be written to by an AP.
It’s recommended that where possible you host a copy of the Activity definition as a JSON document at the Activity Id IRI. This allows the owner of that IRI to assert their canonical definition of the activity and protects against others issuing statements with a conflicting definition. You can host Activity definition metadata yourself, or register your Activity ids within a Profile on the Registry. The LRS will return the canonical definition of the activity within Statements returned via the Statement API when the requested format is ‘canonical’.
The Tetris Prototype uses the Activity Profile API to store a table of high scores shared across all players.
Getting State and Activity Profile Documents
Every Document in the Document APIs has a unique ID, so you can store multiple Documents in each bucket of data. For the State API, this ID is stored in the “stateId” property; for the Activity Profile (and Agent Profile – more on this next blog) the property is “profileId”. This Document ID can be any string, but I recommend using an IRI to avoid conflict with another Activity Provider using the same ID. This is less important when using the State and Activity Profile APIs and targeting an Activity ID you control, but still good practice.
I like to use IRIs for my State IDs to make absolutely sure of avoiding a conflict, but there’s no requirement to do so and the data is already segregated by Activity ID. The spec simply requires the State ID to be a string.
When accessing the State API, the Activity Provider requests a Document matching an Activity ID, Agent object, State ID and, optionally, registration UUID. When accessing the Activity Profile API, Documents are matched only by Activity ID and Profile ID; only the State API can be segregated by registration.
You’ve now covered the State and Activity Profile APIs! Next time we dive into the Agent Profile API!
Go now, store Documents!
