The Directory is a prototype of an un-opinionated storage and retrieval system for Open Badges and an open source community project of the Directory Working Group in coordination with the Badge Alliance.
- To use the Directory API, see the Retrieve Badges page.
- To have your badges added to the Directory, see Add Your Badges below.
- For related information, see these sections below:
Add Your Badges
At the moment the Directory only indexes badge classes. To have your badges added, you need a URL at which the badge class locations are listed in a JSON array. Depending on your site or application, this could be achieved programmatically or simply by creating a file.
Your badge class list endpoint should return a JSON message with the following simple structure:
{
"badgelist": [
{
"location": "http://issuersite.com/location-of-badge"
}, {
"location": "http://issuersite.com/location-of-other-badge"
}
]
}Include an entry for the location of each badge class JSON file you want the Directory to index - these badges will become discoverable via the Directory API.
If you're new to badge classes, each one describes what a single available Open Badge represents - see the specification and assertion guide for more.
When the Directory retrieves a badge listing, it collects up all of the locations and follows them to their badge class definitions.
For instance, let's say you are a badge issuer called badgetastic and your website is http://badgetastic.com. To participate in the Directory, you would expose an endpoint somewhere (on your site or otherwise) that lists all of the badgetastic badges you want indexed. The URL is up to you, but assuming you host it on your site and expose the endpoint at http://badgetastic.com/badgelist - hitting that url we would expect to see a listing of badge locations included in a badgelist array as in the above example. Each of these locations would be expected to lead to a valid JSON badge class.
Let's look at an individual entry from a badgelist array:
"location": "http://badgetastic.com/badge1"The Directory would expect to find a valid badge class JSON listing at the specified location, e.g.:
{
"name": "Badge 1!",
"description": "You speak computers and you can use them too.",
"image": "http://badgetastic.com/badge1.svg",
"criteria": "http://badgetastic.com/badge1-criteria",
"issuer": "http://badgetastic.com",
"tags": [
"Skill",
"Doer",
"Realistic"
]
}For more guidance on creating your badge list (including BadgeKit users), see The Badge List Endpoint.
When you have your badge class listing ready, copy the URL into the below form, together with your other details.
If you'd prefer to register via the API, see Register Using the API.
Who is the Directory for?
The Directory is a community resource. Any issuer of Open Badges can register to have them indexed. The API endpoints can be used:
- in third-party apps
- offering users the ability to search for and browse badges
- to integrate into existing apps
- for example issuer sites offering earners similar badges
- for research
The Directory comprises a search engine for badge classes, so if you're an issuer it provides opportunities for people and organizations to find your badges. Client applications using the Directory API can create pathways to opportunity for badge earners. In this way, the Directory helps people within the badging ecosystem to maximize on the interoperability of badges - issuers can potentially connect their communities of earners to badges from other issuers.
How Does it Work?
When you register your badge list, it will be indexed, then reindexed every 24 hours. This means that if you add or remove badges from the list at your registered endpoint, the Directory will update to reflect that.
Each time a badge list is registered, the Directory support email receives notification, so any problems will be identified and addressed. Any invalid badges will be indexed but will not be returned from the API endpoints.
Approach So Far (+ Future)
This API is a prototype to integrate with the initial version of openbadges-discovery, and to serve as a starting point for an actual badge Directory API for the general Open Badges community.
The prototype is hosted on a free Heroku instance.
There are lots of questions (and discussions) surrounding how a directory would best work, and how it would be implemented.
- In terms of crawling and indexing badges:
- In terms of extending badges (and what impact that may have on searching and retrieving):
Additional Resources
Help and Support
- Post general questions in the Community Google Group and post technical questions in our Dev Google Group.
- Reach members of the Open Badges team directly on IRC (irc.mozilla.org) in the #badges channel.
- Email questions directly to badges@mozillafoundation.org and a member of the team will follow-up.
- Follow or tweet @OpenBadges and @BadgeAlliance.
- Get involved or submit issues via the GitHub repo.