The Experienced API (xAPI) is an industry specified API definition for communicating records of learner interactions. There are is a wealth of information available online relating to xAPI, so much so that it can be hard to know where to start. This tutorial guides you through many of the most useful resources step by step by linking out to them in a logical order.
Please note: The tasks in this tutorial will take you 4-6 hours to complete. In order to fully understand the details of xAPI, you should be prepared to spend several hours reading and working through the additional resources linked from this guide and that you encounter as you work through. Or, if you would rather just get the specification and figure it out yourself, the full xAPI specification is available on GitHub.
- User Types
- Global Admins can set up credentials to send xAPI data to Watershed (but if you don't have a Watershed account, you can set up a free one.)
- Pricing
- Available on all plans.
- Expertise
- This guide is aimed at Developers who can write JavaScript code and understand JSON.
Task 1: Understand xAPI
The first step on your journey is to understand what xAPI is and how and why it is used. This is explained on the xAPI Explained and Benefits sections of xAPI.com.
Take 30-60 minutes to explore those resources until you feel comfortable explaining what xAPI is and why it is used.
Hint: xAPI.com also has an overview for developers.
Task 2: Get a Learning Record Store
As you will have learnt in step 1, to implement xAPI you will need a Learning Record Store which you can send data to. If you do not already have a learning record store (and even if you do), You can register a free Watershed Essentials account. This does not have all the flexible reporting and dashboarding functionality of a paid account, but the xAPI functionality you will interact with as a developer is exactly the same.
Task 3: Send your first statement
The records of learner interactions sent to a Learning Record Store are called xAPI statements. These are JSON objects POSTed to the Learning Record Store using HTTP requests following a specific format.
To send data to your Watershed account, you will first need to set up authorization credentials. This is explained in How do I add an activity provider to Watershed?
If you would like to send the statement using Postman (a popular API development environment), follow the help guide How do I send an xAPI statement to Watershed using Postman?
Alternatively, use xAPI Lab by ADL (a part of the American Department of Defense responsible for learning innovation). Or you could use another API tool such as cURL. If you get stuck using another method, try following the Postman guide first to ensure that you understand the request structure.
Hint: Use Watershed's Data Search and Error Log to help you to debug.
Related: This tutorial covers authenticating using Basic Auth. You can also authenticate using OAuth 2.
Task 4: Play with prototypes
xAPI.com hosts a collection of xAPI prototypes that illustrate how and what data can be sent to a Learning Record Store. Experimenting with these prototypes is a good way to get to grips with xAPI.
Once you download the prototypes, edit the config.js file to use the LRS endpoint and credentials you created in task 2. Then take some time to explore the code, make some changes, and see what happens.
Hint: Use Watershed's Data Search and Error Log to help you to debug.
Task 5: Build your own
By this point you should be pretty conformable with sending xAPI statements to Watershed. You can now try making the connection from your own application. The prototypes used JavaScript, but there are also code libraries available for several other programming languages.
Some of these libraries are more complete than others, so be prepared that you might need to work with them for access the fully functionality of xAPI.
Next steps: Follow best practices
You're now sending xAPI data to Watershed, but are you sending good data that will be useful for reporting? The following guides will help you with best practices relating to xAPI development:
Related: The xAPI Data Sources section of the help site includes a number of other resources you may find helpful.