What are the Document APIs and why should you care?
xAPI’s Statements get a lot of attention and rightly so. Statements are the primary way of tracking the learner and set out a standard data structure for reporting tools to read. But Statements are not the only type of data transmitted via xAPI. xAPI also provides a number of other data buckets (technically known as API Resources) for storage and retrieval of data. Three of these are collectively known as the Document APIs.
Some of you will have also come across the State API, perhaps using it to store bookmarking data for an e-learning course. The Activity Profile and Agent Profile APIs are less well known. They deal with getting and setting data about Activities and Agents respectively, whereas the State API stores data about an Activity/Agent combination. There are some common features the Document APIs share which I’ll cover in this first blog, after which we’ll dive deeper into each in turn.
The Document APIs are primarily designed for storing data that will be retrieved and used either by the Activity Provider storing the data or by another Activity Provider, rather than by reporting tools. They are also used for passing data between a Training Delivery System such as an LMS and an Activity Provider.
The data stored in the Document APIs represents the current situation at a given point in time. If that situation changes, the data will be updated and any old data replaced. Use the Statement API to record a history of what’s happened; use the Document APIs store to the current state of play. For this reason, it’s not considered good practice to build reports based on data in the Document APIs. The data can change at any time so any kind of historical reporting is out of the question. This data might be very useful for a dashboard of KPIs, but most reporting will use the Statement API instead.
The Document APIs store data as “Documents”, like a file on your computer. This means you can store pretty much anything you like in there. This includes text, audio, video, JSON etc. xAPI does not specify a minimum supported storage size, so if you plan to store lots of large documents, you should check with your LRS vendor or make your own storage arrangements.
Documents are stored and retrieved via HTTP request, which means you can send a lot all in one go, but sending too many requests too quickly is resource heavy. For storing a collection of variables, such as bookmarking data, it will often be most efficient to store all your variables as a JSON object in a single document and save these at regular intervals. In a SCORM style course, for example, you can save your bookmarking data every time the learner finishes a slide. Using a POST method instead of a PUT allows you to update individual properties of an object contained in a JSON document, so you can update only those that have changed. This mechanism only works for Documents containing JSON objects, which is a good reason to use JSON objects to store your bookmarking data. We’ll soon be updating our Golf Prototype to include an example of how to achieve this with TinCanJS.
This post has given you an overview of the Document APIs. I’ll follow up next time with a deep dive into the State and Activity Profile APIs. Let me know if you have any questions.
Go now, store Documents!
