Using the Displayer API
This guide is currently being redrafted - be done soon!
With the Displayer API, you can query the Mozilla Hosted Backpack for public badges awarded to a particular earner. See the documentation for a technical overview and for a step-by-step tutorial to using the API, read on.
Earners can use their Mozilla Backpack to organize their awarded badges into groups and to control whether or not a group of badges is publicly available. Given the earner's email address for the Backpack, you can query for the groups of badges they have made public, displaying these within your own site, application or widget.
To display earner badges, you will need to parse assertion data. If you are new to assertions, see these pages first:
- Converting Email to ID
- In the Browser
- In Code
- Querying for Badge Groups
- Querying for Badges in a Group
To discourage storing earner email addresses explicitly, the Mozilla Backpack instead uses a unique ID for each earner. You can pass the earner email address to the convert service to retrieve their Backpack user ID - which you can then use to make Displayer API calls.
You can use the conversion service in a variety of ways, for example manually in your Web browser, using cURL in a terminal or by making an HTTP request in your application code.
To convert an earner email address to Backpack user ID in the browser, visit:
http://backpack.openbadges.org/displayer/convert/email
Enter the earner email address to convert to their ID - copy the returned ID to use in your Displayer API calls.
You can make a REST API request to the convert service in the Mozilla Backpack to convert an earner email to their user ID, which you can then use in your calls to the Displayer API. The URL for the service is the same as the browser version above:
http://backpack.openbadges.org/displayer/convert/email
...presuming you are using the Mozilla hosted Backpack at backpack.openbadges.org
You can try the endpoint out in a terminal/ command prompt using cURL and/or include it in your website or application code. You need to make a POST request to the convert URL, passing the email address of the earner as a parameter. If successful, the convert service will return some JSON data including the earner's user ID for the Backpack.
If you have an account with the Mozilla hosted Backpack, you can try the conversion on your own email address in a terminal as follows:
$ curl -i -X POST -d "[email protected]" http://backpack.openbadges.org/displayer/convert/emailYou should see the response in the terminal when you execute this.
To use the convert service in a simple node.js app, your code might look something like this:
var express = require("express");
var logfmt = require("logfmt");
var app = express();
var http = require("http");
app.use(logfmt.requestLogger());
app.get('/', function(req, res) {
var earnerData = JSON.stringify({
email: '[email protected]'
});
var requestOptions = {
host : 'backpack.openbadges.org',
path : '/displayer/convert/email',
method : 'POST',
headers: {'Content-Type': 'application/json',
'Content-Length': Buffer.byteLength(earnerData)
}
};
var convertRequest = http.request(requestOptions, function(reqResponse) {
var response = [];
reqResponse.setEncoding('utf8');
//store data
reqResponse.on('data', function (responseData) {
response.push(responseData);
});
reqResponse.on('end', function(){
var recData=JSON.parse(response.join(''));
console.log('response: ' + recData);
res.send(recData);
});
});
convertRequest.on('error', function(e) {
console.error(e);
});
// post the data
convertRequest.write(earnerData);
convertRequest.end();
});For simplicity, we write the response out, but in your own apps you will of course do something with the ID (i.e. use it to query for the earner's badge groups).
The convert service will respond with either the failure or success details of your conversion attempt. If successful, the response will be 200 OK, with the following JSON structure:
{
"status": "okay",
"email": "[email protected]",
"userId": 12345
}You can then build the userId value into your requests to the Displayer API for the earner's badges and badge groups.
The convert service may return either of the following errors:
Earner email not found:
404 Not Found{
"status": "missing",
"error": "Could not find a user by the email address `[email protected]`"
}No email parameter included:
400 Bad Request{
"status": "invalid",
"error": "missing `email` parameter"
}In your application code, you will naturally need to parse the returned JSON data in a way that suits your needs. For the above node.js code, this extended excerpt demonstrates retrieving the user ID to use in Displayer API requests:
var recData=JSON.parse(response.join(''));
var earnerId = recData.userId;//use this in displayer api requests nextNote that the user ID is returned as a number, not a text string.
coming soon
coming soon