Mobi-Learning Inc.

unlimited learning, unlimited possibilities

Where to start with xAPI

TinCan API

Experience API (xAPI) is a relatively new standard. In this article, we provide readers with a brief introduction to the xAPI design and implementation. We discuss issues that you may face when integrating xAPI in your solution, such as building your vocabulary and implementing the xAPI interface into your application.

What can I do with xAPI?

From the educator’s point of view, xAPI can be used to gather pieces of data (data about learners/users) that we call statements. These pieces of data can be used to:

  • Track learner’s progress and activity
  • Perform assessment
  • Calculate statistics
  • Trigger actions in the LMS

Similarly, developers interested in xAPI  have  several options. Based on the specification of the xAPI, you can build one of the following:

  • Learning Record Store (LRS)
  • Reporting tool
  • Experience provider
  • Integrated solution

In most cases developers will be interested in extending their educational apps with xAPI and building experience providers; let’s then focus this time on experience providers and adding xAPI client libraries into the applications. Before we do that, however, we would like to provide a broader context.

Assessing your needs

Needs assessment is the base for successful implementation; therefore you start by thoroughly assessing your needs and identifying use cases that you want to implement. Because xAPI is a fairly new standard that is still under development, you may find that there are elements that have to custom make. Other elements may exist either as open source products, components of your LMS or stand alone commercial applications. In any case you have to start by asking needs assessment questions, including the ones proposed below.

I. What are the activities that your application provides?

The first step in your xAPI design should be the identification of activities that will be reported through xAPI. All elements such as learning units, practice tasks, quizzes and tests are candidates for such activities. Each identified activity should be described using the format presented in the following table.

Table 1. The activity documentation schema
Name IRI (URI) Description
Explanation The name of the activity A unique identifier of the activity in the URI style The natural language description of the activity
Example quiz1 The first quiz testing the knowledge of the xAPI standard

II. For each activity, what verbs can be used in the context of the activity?

For each activity you have to identify the verbs that will be used in its context. The vocabulary that could be potentially used in this context depends on your organization and application. You may decide to use generic vocabulary that is designed by ADL and published on their website. You may also follow the example of several communities of practice (CoP) and build your own vocabulary. In such case, you should also follow the format used by ADL and provide the following information for each verb:

  • Verb term
  • Usage description
  • IRI (URI)
  • Related match – term description from wordnet
  • Scheme e.g. xapi:verbs

ADL and the xAPI community are currently working on an ontology based solution that will help CoP in vocabulary maintenance and extension. The idea is strongly based on RDF and several other ontologies. Such tool is needed if we want to integrate xAPI records from various sources and effectively build e-portfolio. We look forward to this development.

III. What is the platform/language that you use in your application?

With the list of activities and verbs ready, you have to decide which technology you want to use to implement the xAPI client. Also here you have several options. Currently Rustic Software provides xAPI developers with eight libraries on their website:

  • TinCanJS: a JavaScript library supporting xAPI 0.90, .95, and 1.0.0
  • Objective-C Library: Supports Tin Can .95, 1.0.0, basic statements/state and attachments.
  • Java Library: supports Tin Can .95 and 1.0.0
  • PHP Library: supports Tin Can 1.0.0+
  • Python Library: supports Tin Can 1.0.0+
  • .NET Library: supports Tin Can 1.0.0+
  • TinCanObjC – Offline: Offline wrapper for TinCanObjC
  • TinCanAndroid – Offline: Offline wrapper for TinCanJava with Android

The libraries listed there are available free of charge as open source projects available through Git. Developers are also encouraged to share their implementations in other languages to help the xAPI community grow.

Select the library for your language, download and include it as a dependency into your project. Below, we show an example of the code in PHP that creates a simple statement and sends it to the LRS.

The first step of this process is creating a $lrs object that will encapsulate the proper endpoint and credentials to connect to the LRS.

$lrs = new TinCan\RemoteLRS(
   '< UserName >',
   '< Password >'
Fig. 1. PHP code to create LRS object


With the $lrs object created, you are ready to prepare the statement. To do so, you have to define activity, actor (the person performing the action in the activity) and verb (the action).

$actor = new TinCan\Agent(
   [ 'mbox' => '' ]
$verb = new TinCan\Verb(
   [ 'id' => '' ]
$activity = new TinCan\Activity(
   [ 'id' => '' ]
$statement = new TinCan\Statement(
   'actor' => $actor,
   'verb' => $verb,
   'object' => $activity,

$response = $lrs->saveStatement($statement);
if ($response->success) {
   print "Statement sent successfully!\n";
else {
print "Error statement not sent: " . $response->content . "\n";

Fig. 2. PHP code to report a simple statement


The $lrs object provides a saveStatement method that takes the statement as a parameter and returns a response. Based on the status from the response, you can verify if the operation was successful or retrieve more detail information about the error if the operation failed.


In order to balance interoperability and the varying security requirements of different environments, several authentication options are defined in the xAPI specification. The LRS must at least provide one of the following authentication methods: OAuth 1.0, HTTP Basic Authentication (with user and password) or Common Access Cards (CAC). The LRS must also handle making, or delegating, decisions on the validity of Statements, and determining what operations may be performed based on the credentials used. Nowadays, OAuth is a very popular authentication mechanism used by large portals and institutions to provide single sign on (SSO) for their users and employees.

There are three OAuth endpoints that have to be provided by the LRS that supports OAuth. Each of them accepts key and secret and responds with credential (initiate and authorize endpoints) or a token (token endpoint) or error message (all of them):

  • Temporary Credential Request OAuth/initiate
  • Resource Owner Authorization OAuth/authorize
  • Token Request OAuth/token

The first endpoint is used to initiate the communication between client (experience provider) and LRS. The next step is authorization, when the permissions of the resource owner are verified. Finally, through a token endpoint the client receives the token that can be used in the further communication. Additionally, if OAuth 2.0 is developer can set redirect URL and automatically redirect user to the specified place. This function is not available in OAuth 1.0 and manual action of the user (entering an authorization code) is required.

What’s next?

The approach described in this article is a start. You should be able to design your vocabulary and run first, simple statements. Still, there are some considerations to bear mind, such as authorization method (HTML Basic Authorization vs. OAuth), building a trust relationships with existing solutions. You also should remember that the communication with LRS should not block the normal operation of the application. In other words, it should be done asynchronously and with mechanisms allowing the work off-line. We will discuss those topics in future posts to be published soon.