Contact Us 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:

866.497.2676


Tin Can API Tech Overview

What is Tin Can again?

The Tin Can API is a web service that allows for statements of experience (typically learning experiences, but they could be anything) to be delivered to and stored securely in a Learning Record Store.

The web service allows clients to read and write experiential data in the form of “statement” objects. In their simplest form, statements take the form of “I did this”, or more generally “actor verb object”. Tin Can also provides facilities for more complex statement forms, a built in query API to help filter statement streams, and a state API that allows for a sort of “scratch space” for consuming applications. All communication may be done securely via SSL or OAuth.

Back to top ▲

Why should I care, as a developer?

It’s no exaggeration to say that there is a revolution underway in the e-learning industry. If you already consider yourself to be a part of that industry, it will only be a matter of time before you’ll need to familiarize yourself with Tin Can. But, even on broader terms, Tin Can is presenting an opportunity to create systems and components that comprehend a novel format for experiential data. The Tin Can API has also been built to support a distributed architecture, where statement streams can be propagated to many places, and driven by many sources. Hooking into streams of information already being produced by major learning based vendors and applications could offer some interesting mash ups and programming possibilities. Not to mention, the Tin Can API can offer real value in worlds completely disjointed from e-learning.

Back to top ▲

What is a statement? What does it look like?

Statements are the bread and butter of Tin Can. They dictate the format for the specific moments in a stream of activity. They convey an experience which has occurred, or may be occurring, and typically have a good english translation, for instance, “Bob completed ‘Truck Driving Training Level 1’” or “Sally experienced ‘Solo Hang Gliding’”. Let’s convey the latter statement in terms of a Tin Can statement object…

Simple Tin Can statements take the general form of “[actor] [verb] [object]”. These labels coincide with the field names on a statement object. So, in conveying the information that “Sally experienced ‘Solo Hang Gliding’”, we can quickly spot “Sally” as the actor, “experienced” as the verb, and “Solo Hang Gliding” as the activity. Ignoring the structure of the specific parts, the statement object itself would take this structure in JSON format:

{
    "actor": "Sally",
    "verb": "experienced",
    "object": "Solo Hang Gliding"
}

 
This is at least simply useful, but simple strings can only take us so far. How do we know which Sally we mean? Which ‘Solo Hang Gliding’ activity was it, one that was part of military training, one from a commercial enterprise, or something self directed? Let’s expand these parts and show a valid Tin Can statement:

{
    "actor": {
        "name": "Sally Glider",
        "mbox": "mailto:sally@example.com"
     },
     "verb": {
         "id": "http://adlnet.gov/expapi/verbs/experienced",
         "display": {"en-US": "experienced"}
         },
     "object": {
         "id": "http://example.com/activities/solo-hang-gliding",
         "definition": {
             "name": { "en-US": "Solo Hang Gliding" }
         }
     }
}

 
Mostly, we’ve added structure here to ensure we have a way to uniquely identify the component parts. This helps us correlate statements about the same person, activity, or verb. There’s also some structure added to provide information about our objects, like name (other descriptive fields are available, see the Tin Can API specification for details).

We can also add a lot more to a statement, in the form of statement context (“Sally completed ‘Solo Hang Gliding’ in the context of ‘Army Training Level 1’” or “Bob completed ‘Truck Driving Training Level 1’ on his Android phone, under the instruction of Dan”) or you can attach results to a statement (“Bob passed ‘Truck Driving Training’ with score 90%”). You can even declare custom fields on a statement, in the form of extensions. You can find a much more detailed explanation of statements in our Statements 101 page.

Back to top ▲

How do I make my own statement?

To make things a little easier for you (and to make experimentation a snap,) we’ve created a Statement Generator. Just fill in the fields with your desired actor, verb, object, etc. and the Statement Generator will create a statement for you. You can also use the generator to paste in statements that you’ve created on your own and validate them (or if you’re having problems with your statements, use the validator to find out what’s breaking them.)

We’ve also developed a Tin Can bookmarklet. It’s a really quick and easy way to let you see some statement generation in action. It allows you to send a statement that you’ve “experienced” any webpage, just by visiting the page and clicking the bookmarklet. Install the bookmarklet, and you can be generating Tin Can statements in just a few minutes.

For a much more in depth look at Tin Can statements, check out our Statements 101 page.

Back to top ▲

How do I send the statement?

If you’re savvy on the command line, one easy way to try out sending a statement is through using the “curl” command. As an example, let’s post our example statement above to the public endpoint hosted on SCORM Cloud. In this case, we’re specifying an HTTP POST, using Basic Auth with a blank username and password (as expected by the public endpoint), and specifying the content type as “application/json”.

curl  -H "Content-Type:application/json" -H "X-Experience-API-Version:1.0.0" -u ":" \
https://cloud.scorm.com/ScormEngineInterface/TCAPI/public/statements -d \
'{
    "actor": {
        "name": "Sally Glider",
        "mbox": "mailto:sally@example.com"
    },
    "verb": {
         "id": "http://adlnet.gov/expapi/verbs/experienced",
         "display": {"en-US": "experienced"}
    },
    "object": {
         "id": "http://example.com/activities/solo-hang-gliding",
         "definition": {
             "name": { "en-US": "Solo Hang Gliding" }
         }
    }
}'

 
To see this statement (along with others posted to the endpoint), try loading up the following URL into your browser (just leave the username and password blank when prompted):

https://cloud.scorm.com/ScormEngineInterface/TCAPI/public/statements?limit=10&prettyPrint=true&version=1.0.0

See our instructions for setting up your own private LRS with SCORM Cloud, if you’d like to do that.

Back to top ▲

What else is there in the API?

You’ve seen how to send statements to the API, but you might be wondering how you can get them back out. In true REST form, invoking the query call is a matter of issuing a GET on /TCAPI/statements. The query API provides a number of parameters to filter the returned set of statements. This includes filtering on a statement’s actor, verb, and object, but also includes ways to filter based on parts of the statement context, or limit the results with time boundaries. This allows for built in capability to ask things like “Who has completed ‘Solo Hang Gliding’ since yesterday?” or “What’s all the activity happening in the context of ‘Ping Pong’ during last month?”. The full list of available parameters are listed in the Tin Can API spec.

In addition to the statements API, Tin Can also specifies a state API, which allows applications to save arbitrary key / document pairs in the context of a particular actor, a particular activity, or some combination of actor and activity. Imagine documents like “Bob’s profile information for the Truck Driving Training program” or “Sally’s list of notes from ‘Solo Hang Gliding’” or “All comments for ‘Truck Driving Level 1’ course”. This allows for some applications, particularly those launched across different platforms and devices, to have an easy place to put some useful state. The Tin Can API also provides a few other calls that assist in the discovery of activity and actor information.

Back to top ▲

How do I report on this stuff?

That’s a great question, and the answer is still forthcoming. In many ways, the power of the Tin Can API is realized by providing a loose structure that gives applications some flexibility in how they describe experience data. Reporting is an area of Tin Can that, beyond the query API, is technically outside of the scope of the specification. But, it’s an important practical concern, which can partly be addressed with generic tools, and otherwise with custom built reporting.

Some obvious common ground among all statements is dictated by the standard, and some general reporting concepts can be driven by that, such as grouping statements by actor, verb, object, or contextual information. But, there are also a lot of possibilities around creating reports that are specific to the type of experiences you are reporting. To take our Ping Pong example, we could get some interesting facts from generic reports, such as how many matches have been played in total, how many have been played by specific players, and perhaps how many wins and losses happened for a particular player. But, a reporting layer specific to Ping Pong statements might want to feed these wins and losses into a system that can calculate a wide range of statistics and reports, like a board of rankings, Elo scores, and so on.

Back to top ▲

Is there a best practice for authentication with an LRS?

The LRS will support authentication using at least one of the following methods:

  • OAuth 1.0 (rfc5849), with signature methods of “HMAC-SHA1″, “RSA-SHA1″, and “PLAINTEXT”
  • HTTP Basic Authentication
  • Common Access Cards (implementation details to follow in a later version)

Back to top ▲

How can I get my hands dirty?

We’ve got a number of resources and tools that you can start digging into today, and we’re actively working on putting together more. You can find them all on our resources page. Included there are a number of technical documents, including the core Tin Can specification. You’ll also likely find the quick start guide and supporting documents to be useful there. If you’re looking to get your hands on some code, you can check out some of the open source Tin Can prototypes. A good place to start there may be the “StatementIssuer” project, which illustrates how to take some essential pieces of information and create a statement from them. Then, you might want to see how we’ve implemented some Tin Can functionality in a bigger context. For that, we’d recommend digging through the GolfExample_TCAPI project. For those with true technical grit, you can see the most comprehensive interaction with Tin Can by looking through the testing code that lives in the “tests” folder, alongside the ClientPrototypes folder.

If you’d like to see the Tin Can Prototypes in action already, you can play with live versions of them in our Tin Can Prototypes section of this page.

To see the basics of building an LRS, see the “Building a Learning Record Store” page.

Please send us your thoughts and questions as you dig into Tin Can. We’re happy to provide any answers we can, and we’d love to hear about your progress as you explore the use of Tin Can in your own application. We’ve planned to add several more articles on this site to help you through that, including a deeper introduction to statements, actors, activities, and more. If you’d like to stay informed about the latest Tin Can API news, get email updates from us.

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.

Close