Five Things a Web Developer Needs to Know About the xAPI

If you are an instructionaldesigner, you should read the LearningSolutions article published October 13, 2014, “Ten Steps to Plan and Communicate Your xAPI Design to a Web Developer.”

If you are a web developer, andhave been asked to implement an Experience API (xAPI) solution that has beendesigned by an instructional designer in the training department, you may bewondering what the xAPI is and what it will take to implement. You may not beaware of the xAPI specification yet. This article will help you get started. Itprovides a conceptual framework for understanding what the xAPI is and what itdoes.

The xAPI is extremely useful inthat it can be expressed as both human-readable and machine-readable in thesame format because it uses natural language. It is claimed that the xAPI cantrack anything. Anything is reallyunsettling for a web developer, but don’t fret. Here are five of the basics toget you started in developing with xAPI.

1. Make sure you have the required technical knowledgeand skills

As with any web-developmenteffort, certain programming languages and technologies are needed to makethings work. The following are key technical knowledge and skills that you willrequire:

• Application Programming Interfaces (APIs)(ease the ability to share data between applications)
• JavaScript Object Notation (JSON) (a popular, light-weight data format forAPIs)
• REST (an architectural style applied to webservices)

The data format xAPI uses isJavaScript Object Notation (JSON). While JSON has JavaScript in its name, thereis no dependence on JavaScript for programming. If you are familiar witheXtensible Markup Language (XML), then JSON should come naturally to you. LikeXML, JSON is syntax used for the storage and retrieval of structuredinformation. JSON uses a hierarchical node structure, but unlike XML, the orderof the siblings does not matter. Each JSON “node” is a string representation ofa container of other “nodes,” or a name/value pair, or an array of name/valuepairs. There are no attributes like there are in XML. JSON is inherently moreefficient than XML, requiring less machine time to process the data (on eitherend).

To align with current web bestpractices, a RESTful approach is used with all xAPI requests. HTTP methodscombined with RESTful practices work through HTTP requests to store, modify,retrieve, and delete data. For the purposes of xAPI, you only need a conceptualunderstanding of REST as the technical details are built-in to the xAPIrequirements and resources that use xAPI.

2. Learn the basic terminology

To understand the xAPIspecification, you will need to read the documentation, but first, there are afew basics that you should understand:

Statement

Most xAPI data is communicatedthrough Statements. A Statement is represented in a JSONformat and includes, at a minimum, the actor,or user who is being tracked, the verb,or action they are taking, and the object.(Figure 1)

Figure 1: The basic elementsand structure of an xAPI statement

The object can be an activity,another actor, or a previous experience. There are other JSON components thatare mandatory or optional, but the actor, verb, and object (usually in the formof an activity) are the most important.

Actors

An Actor is an individual orgroup, represented by a unique ID that can be associated with a persona. Apersona is a particular representation, usually an account (email orotherwise), corresponding to a specific set of tasks used by the account. Someexamples of unique IDs that could be used are email address or applicationaccounts (e.g., Open ID, Twitter, Facebook, Google, etc.)

Verbs

The Verb in an xAPI statementdescribes the action performed during the learning experience. The xAPI doesnot specify any particular verbs. Instead, it defines how to create verbs sothat communities of practice can establish verbs that are meaningful to theirmembers and make them available for use by anyone. Verbs have uniqueidentifiers that reference an embedded definition to assist in disambiguation. Forexample, using the verb, fired, isambiguous. A definition is used to disambiguate the verb. You may define firedas “launched a projectile,” or “terminated an employee.” Verbs are the primaryproperty used to sort statements, so using verbs correctly and consistentlywithin a community of practice is very important.

Object

In object-oriented programming,a generic object acquires specifically defined properties as it becomes a morespecific type. In grammar, the object of a sentence can take the form of anoun, pronoun, phrase, or clause. Objects in xAPI have both of thesecharacteristics. An object used in an xAPI statement has an objectType, whichdetermines specific properties for the object. There are three objectTypes:Activity, Actor, and Statement.

• ActivityObjectType: An object of the type activityis the most common type. Examples of activities in xAPI statements are “Janeattempted the cake recipe,” “Jane passed the chemistry quiz,” and “Janeequipped virtual sword” (i.e., in a virtual world or simulation). Activityobjects are extremely granular and can identify something as large in scale asa specific virtual world or as small as a single virtual chair in that world. Toput it another way, sometimes the activity object is something the learner uses(recipe) rather than something the user is part of (a cooking class).
• ActorObjectType: An object of the type actoris useful for capturing person-to-person interactions. Examples would be “Andysent Jason a message,” “Jason invited Andy to join a business seminar,” or “IntelligentTutor recommends training to Andy.” An actor object, like the defined actor, takeson a particular persona.
• StatementObjectType: An object of the type statementis useful for applying actions to previously used xAPI statements. In thesame way grammar uses clauses, sometimes a single verb and object isn’t enough.Examples would be “Andy liked that Jason passed Biology 101,” “Andy commentedon Andy posted picture of a sunset,” or “Andy shared that Andy got quizquestion #1 wrong.”

Agents

An actor that is an individualis called an agent. As there are specific endpoints and functions in xAPI thatonly work on individuals, this distinction is necessary.

Context properties

Context properties are some ofthe most important elements in xAPI. They allow the grounding of a statement byproviding a context in which the experience took place. Pertinent information, suchas the instructor of the content, the location or language the activity tookplace in, and related activities are all baseline parts of context. Furthermore,context can be extended to allow communities of practice to define their ownfields. The context property can be used to define an “activity tree” thatrelates higher-level xAPI statements to more granular statements. This approachmakes reporting and analytics easier to interpret.

IRIs

The uniqueness of objects andverbs are dictated by full InternationalizedResource Identifiers (IRIs). IRIs are similar to URIs and URLs, which may be morefamiliar to web developers, but an IRI can use international characters and isstill unique. A best practice in xAPI is that the base portion of the IRI is adomain controlled by those creating verbs and objects. Figure 2 shows IRIstructure and best practices:

Figure 2: IRI structure andbest practices

While a URL always begins with theauthority, https://<domain name>/<path>, a URI or IRI can referencea file share or other type of address which may begin with a different type ofauthority.

When you establish an IRI, make sure theauthority is under your control so that changes to the authority, domain, orpath do not adversely affect your IRI. Also, make sure you use a namingconvention that is descriptive and unique.

In the graphic above, theact:my-activity01 is a bad IRI because the web developer doesn’t own theauthority, act. Thehttps://example.com/activity/01 is a bad IRI because the activity name, 01, has no meaning, making it difficultto interpret and reuse.

LRS and endpoints

Statements are validated andstored by a Learning Record Store (LRS). AnLRS can be part of a learningmanagement system that supports xAPI, or a standalone system. The LRS isresponsible for implementing multiple sub-APIs (more accurately, xAPI Resources), each of which have endpoints. Anendpoint is simply a URL within theLRS that listens for HTTP requests. The xAPI is actually a set of sub-APIs andeach sub-API has its own endpoint. The sub-APIs are described in thetable below.

Table 1: Sub-APIs, theirfunctions, and examples

3. Go granular

Do you remember learning toavoid run-on sentences in grammar class? The same rule applies to xAPI. Whileverbose statements are allowed, xAPI statements are easier to consume in smallamounts so that they can be queried and sorted quickly. Collecting a lot ofinformation during an activity session and then sending one giant statement atthe end will make reporting and analytics more challenging. Instead, you canuse parts of the statement like the context property and timestamp to describethe bigger learning picture. An effective practice commonly used by developersis to send one statement to establish the overall activity, and a collection ofmore granular statements for each step within the overall activity.

Another important exercise isto determine the granularity of activities. Since an activity can be anythingwith an IRI, deciding on what constitutes a distinct activity is important forstorage and retrieval of statements. For example, if all the steps in a processwere embedded in a single activity statement, it would be more difficult toproduce metrics on the individual steps. By using separate statements for thesteps in the process, each step is assigned a unique identifier, allowing it tobe queried, reported, and analyzed more easily.

4. Establish standards for organizational adoption ofxAPI

The specification currently hasfew requirements when it comes to defining your own vocabulary for buildingxAPI statements. While this openness and flexibility enables powerful newopportunities, it also presents new challenges. As a developer, you must notonly be familiar with the syntax of different xAPI verbs, activities, andvocabulary found within the specification, but also with their intended use andmeaning within the intended learning environment. If this is your organization’sfirst xAPI project, you should define and document the verbs you use in yourstatements. This documentation is the beginning of a controlled vocabulary thatwill help to ensure your organization uses verbs and statements consistently infuture xAPI projects. If your organization has been working with xAPI for a while,make sure you follow the verb usage standards established in previous projects.

5. Expand your xAPI knowledge and skills

The open process by which thexAPI was developed continues to be one of its strong points. There are manyresources available to help you expand you xAPI knowledge and skills. Takeadvantage of LRS documentation, open-source prototypes, and social-media siteswith active xAPI discussions.

If you want to take a deeper dive into the xAPI, thefollowing list of resources may be helpful:

• ADL’s Introduction to the Experience API: What itis, why we did it.
• The actual Experience API specification: What everyone is so excited about. This isprobably the most important resource that your developer can have.
• ADL SCORM xAPI wrapper: Simplifies communicationfrom a SCORM package to an LRS (using xAPI, naturally).
• ADL’s xAPI Developer Tool and Examples: Thiscovers the ADL open-source learning record store, client examples, a JavaScriptxAPI wrapper, and ADL xAPI verb script. Everything here can also be found atthe ADL GitHub page.
• Resources from ADL’s first xAPI BootCamp: These are a selection of materials from ADL’sJune 2014 xAPI event in Orlando, FL.
• Nine Awesome Reads About the Experience API, and One Cartoon: Exactly what it says on the tin.
• The Experience API—Liberating Learning Design: The eLearning Guild’s xAPIResearch Report

Conclusion

This article provides astarting point for understanding the xAPI. A working knowledge of JSON, REST,and APIs will get you started writing Statements. Each of the parts of an xAPIstatement work together to describe a learning activity and its relationshipwith learners.

Implementing actors, verbs, andobjects correctly, while applying the appropriate context and granularity,enables you to track, report, and analyze learning- and performance-softwaresolutions. Establishing organizational standards and conventions will ensurethat your organization gets the most out of its xAPI implementations. A greatplace to start is to explore and reuse open-source resources from webdevelopers who are already in the field creating xAPI.

From the Editor: Want more? Explore the xAPI at DevLearn!

At DevLearn 2014 later this month there will be two xAPIhighlights. The first is xAPI Hyperdrive, a new competition designed to showcase thebest examples of innovation using the Experience API; it takes place Tuesday,October 28 at 3:30 PM, the afternoon before the conference begins.

During the conferenceitself, October 29 – 31, we offer a brand-new featured track—xAPI in Practice—that is included with conference registration. The xAPI inPractice program consists of a group of sessions that run throughout theconference, offering you the chance to explore real-world case studies showinghow xAPI is being used in organizations today. Learn about the business valueof xAPI and the opportunities it presents to improve your practice.