Contact Us Support Forum Get Email Updates

Thanks! Someone will be in touch with you shortly.

Rather just email us? Email us here.
Rather speak with someone in person?
Call any time with Tin Can questions:


Deep Dive: The Document APIs Overview

Posted by

Categories: Best Practices, Deep Dive, Document APIs, Standards, Tin Can

Posted 16 February 2015


What are the Document APIs and why should you care?

Tin Can’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 Tin Can. Tin Can 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. Tin Can 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!

  • Jessie Chuang

    Andrew, Thanks for the writing. I have a question about “it’s not considered good practice to build reports based on data in the Document APIs”. I think reporting tools can visualize a learning status above the level of state API data from one AP, and real-time feedback(level up, leaderboard) to the learners about their progress on activities across systems. What do you think?

  • Andrew Downes

    Hi Jessie!

    I absolutely agree! This is the point I was trying to make when I said “This data might be very useful for a dashboard of KPIs”. Thanks for highlighting this and giving additional examples.


Tin Can API Email Updates

* indicates required

Tin Can API Email Updates

Thanks for signing up for the Tin Can API newsletter!

Make sure to follow us on Twitter @ProjectTinCan,
and tweet this page to let others know about the Tin Can API.