BadgeKit API Introduction

BadgeKit is a set of tools to help you use the Open Badges framework within your own sites and applications - to find out more about Open Badges see OpenBadges.org.

BadgeKit is currently available through two channels: the private beta hosted version (for partner organizations - sign-up has now ended), or download the code from GitHub and install it on your own server.

To use BadgeKit:

• Setup your BadgeKit account or instance:
• Sign-up at BadgeKit.org has now ended. BadgeKit is currently aimed at supporting organizations who want to implement a full badging system within existing sites. In such cases you will receive a response including instructions for accessing your new BadgeKit account via Mozilla Persona. Otherwise your response will detail alternative options and outline our future plans for BadgeKit to accommodate lighter-weight badging systems. OR
• Download the code from GitHub and install it on your own server: Self-Hosting Guide.
• Connect to the BadgeKit API to manage badge access for your earners. The application handles badge creation, issuing and assessment - so much of the badging work is already done!

BadgeKit comprises a Web app and an API. Whether you're using the hosted version or hosting your own, you need to integrate BadgeKit with your own earner-facing site using the API.

If you are planning to self-host, see the following additional resources:

• Using BadgeKit API - to get started using the API in your earner site
• BadgeKit User API - to access the User API (for managing user accounts for BadgeKit via API endpoints)
• Troubleshooting Guide - if you're having setup problems

Using the Hosted Service:

• For an overview of using the BadgeKit hosted service (for issuer admin users) - see the BadgeKit Tutorial.

Understanding BadgeKit

• For definitions of any badging terms you are unsure of - check out the BadgeKit Glossary.
• If you're a new issuer - see the Open Badges Issuer Onboarding docs.
• For a list of BadgeKit and Open Badges development utilities - see the Resource Page.

What Is BadgeKit

BadgeKit makes badging easier. If you want to create a badge issuing application or to integrate an existing system with Mozilla's Open Badge Infrastructure (OBI), BadgeKit will help you to make that happen. The tools within BadgeKit support all of the processes in a badge issuing application, from designing and defining to reviewing and awarding.

You can use the BadgeKit tools out of the box or can tailor them to fit your own requirements. Whether you want to provide one, some or all of the badging processes, you will find the tools here to build your system quickly and easily.

For a general overview of what BadgeKit does and how the API and Web app fit together, read on.

What are the component parts in BadgeKit?

BadgeKit comprises two main components:

• a Web app
• an API

The Web app provides a user interface through which issuers can create badges, publish them and manage the data for earner applications. Since the BadgeKit app is intended to provide back-end processing, with your own sites handling earner interaction, the API combines with the app to facilitate the remaining processes in a badging system. Your sites can use the API methods to deliver earner communication in a way that suits your own community.

What can I do with the BadgeKit API?

Since BadgeKit handles much of the back-end processing in a badging application, you can focus your development efforts on the experience you want your badge earners to have.

Issuers can use BadgeKit and the API in conjunction with their own sites as follows:

• Web app: create and publish badges
• API: retrieve available badges
• Issuer site: present available badges to earners
• Issuer site: allow earners to apply for badges
• API: forward application data
  • can include earner evidence
• Web app: review applications (including evidence)
• making awarding decisions
• API: receive award data at webhook
• Issuer site: interact with earner regarding award
  • optional steps include offering to push badge to a backpack

What is the BadgeKit API?

The BadgeKit API includes a few different endpoints to let you interact with various parts of the badging process. Badge issuers can use BadgeKit together with the API to create badges, to list available badges on their sites, process applications and to issue badges to successful applicants. API access falls into the following categories:

• badge listing
• badge issuing
• assessment and review

BadgeKit itself handles much of the badging process, including badge creation, review and issuing. In your own site, you can integrate with BadgeKit to provide a custom interface for your badge earners.

The API provides endpoints through which you can interact with badge data and webhooks which you can configure to receive notification of badging events. By using these two in conjunction, you can control the earner experience while BadgeKit takes care of the admin back-end.

Listing

You can use the API to list available badges for potential earners. BadgeKit itself handles creating badges, so your application can simply retrieve the badge data and present it within your own environment.

The API uses straightforward request calls and returns JSON data, which can readily be parsed by many of the technologies currently in use.

Issuing

The badge issuing process can vary:

1. badges can be issued directly

• earner gives an email address, issuer gives earner a badge

2. badges can be issued using claim codes

• e.g. instructor gives earner a code on completing a workshop
• earner enters the claim code to receive a badge

3. badges can be issued automatically

• e.g. a milestone badge, which is issued on completion of a set of other badges

4. badges can be issued following assessment by a reviewer

• some badges require assessment by reviewers, sometimes involving submitted evidence and a rubric

BadgeKit therefore supports the following processes:

• issuing badges directly
• submitting claim codes to receive a badge
• issuer sites can issue using claim codes via the API
• reviewing earner applications for badges
• issuer sites can plug into the API to issue following application review
• storing and viewing application evidence.

Note that however you issue a badge, BadgeKit will not carry out any earner communication. Instead, the API sends notification to your webhook URL when a badge is issued - you can then contact the earner.

The BadgeKit Web app also includes a series of administrative utilities to aid badging processes. For example, the creator of a badge can include a note for the reviewer. The interface also provides the ability to view badge evidence and rubrics when reviewing earner applications. The badge creation flow in BadgeKit is generally designed to prepare the issuer for assessment within the same environment.

Your own site can detect issuing events from BadgeKit via a webhook URL, letting you respond and tailor the issuing experience to your earners.

Assessment and Review

When a potential earner sees a badge listed that they decide to apply for, they can submit evidence. Within the BadgeKit app, the assessor can then review this evidence against the badge criteria (sometimes in the context of a rubric), before deciding whether to issue the badge to the applicant. The BadgeKit Web app handles submitted evidence from badge applicants and allows reviewers to submit assessment decisions.

Your own site can also receive notification of reviewing events via the BadgeKit webhooks, responding to assessment decisions and connecting with your earners.

Webhooks

To use the API, an issuer site needs to be able to communicate with the BadgeKit processes. To this end, the API outputs messages when certain badging events occur, such as an assessment being completed or a badge being issued. The issuer site can receive notification of these events by configuring a webhook URL for the system within the BadgeKit instance. If you are using the hosted site, contact us to configure your webhook. If you are using a self-hosted instance of BadgeKit, you can configure this yourself.

An issuer site can therefore respond to the badging actions facilitated by BadgeKit, integrating them with its own functionality.

See the section below for an introduction to accessing the BadgeKit API and the API reference documentation for an overview of the endpoints/ webhooks you can use in your applications.

Authentication

When you access the BadgeKit API endpoints, you must include a JSON Web Token auth parameter. This must be signed by an established shared secret between client and host.

How do I use the BadgeKit API?

The BadgeKit API endpoints are accessed via request methods which return JSON data. Which methods you need to call will depend on the badging processes you want to carry out.

Here is a simplified BadgeKit API request to retrieve the list of badges:

GET /badges

Many of the endpoints accept parameters to configure the results.

Here is an example of what the response JSON might look like:

{
    "badges": [
        {
          "name": "Algebra 101",
          "slug": "algebra-101",
          "strapline": "Essentials of algebra",
          "earnerDescription": "Can solve basic algebra equations",
          "consumerDescription": "Grasps essential algebra technique and notation",
          "issuerUrl": "http://example.org/issuer",
          "rubricUrl": "http://example.org/rubric",
          "timeValue": 10,
          "timeUnits": "minutes",
          "limit": 5,
          "unique": false,
          "imageUrl": "http://example.org/algebra-101-badge.png",
          "archived": false
    },
    {
          "name": "Advanced Freestyle Swimming",
          "slug": "adv-free-swim",
          "strapline": "Swims freestyle at expert level",
          "earnerDescription": "Freestyle swimmer with expert stroke technique",
          "consumerDescription": "Demonstrates advanced mastery of freestyle stroke",
          "issuerUrl": "http://example.org/issuer",
          "rubricUrl": "http://example.org/rubric",
          "timeValue": 6,
          "timeUnits": "hours",
          "limit": 1,
          "unique": true,
          "imageUrl": "http://example.org/adv-free-swim-badge.png",
          "archived": true
    },
    {
          "name": "Spreadsheet Administrator",
          "slug": "spreadsheet-admin",
          "strapline": "Edits and manages spreadsheets",
          "earnerDescription": "Can carry out essential spreadsheet admin tasks",
          "consumerDescription": "Spreadsheet user with basic formulae and functions",
          "issuerUrl": "http://example.org/issuer",
          "rubricUrl": "http://example.org/rubric",
          "timeValue": 3,
          "timeUnits": "days",
          "limit": 50,
          "unique": false,
          "imageUrl": "http://example.org/sprd-admin-badge.png",
          "archived": false
    }
    ]
}

As you can see, a badge consists of an image and a range of data items. For more information about badge metadata, see the Assertion Documentation. For a step-by-step guide to using the API endpoints, see Using BadgeKit API. For an explanation of how assessment works in BadgeKit, see Assessment with BadgeKit.

Next Steps

If you want to start building a self-hosted BadgeKit instance now, see the Self-Hosting Guide and video from the Self-Hosting Tech Panel. If you want to integrate BadgeKit with your own site, see the API wiki.