Skip to content
This repository has been archived by the owner on Sep 2, 2020. It is now read-only.

Home

Jump to bottom
SueSmith edited this page Sep 29, 2014 · 22 revisions

BadgeKit API

Welcome to the BadgeKit API repo!

For an overview of the API endpoints, including sample data sent and received, see the docs. For more detailed guides to carrying out common processes with the API, see this wiki.

Issuers can use the BadgeKit tools to facilitate creating, managing and awarding Open Badges. You can use the BadgeKit API on its own or can combine it with the BadgeKit Web app.

The BadgeKit Web app provides an administrative interface for badge issuers to create, design, define and publish Open Badges. The app also supports processing applications for badges, so that you can manage the full lifecycle of a badge, from creating it to awarding it.

The BadgeKit API handles the data for badges and provides a series of webhooks you can use to build custom interfaces for your community of badge earners (or to implement badging within your existing site or application).

Your earner-facing site can plug into the BadgeKit API to retrieve badge information and receive callbacks when certain badging events occur, such as a badge being issued. This allows you to configure all aspects of interaction and communication with your badge earners, while BadgeKit manages the back-end.

Once you have BadgeKit setup, you will have to carry out a few steps to integrate it with your own site. See the Next Steps section below for guidance.

Contents

Example usage

You can use whichever elements of BadgeKit suit your own community's needs. Here are some examples of what you can do with the API:

  • retrieve the data for available badges
  • badges created with the Web app if you're using it
  • submit an earner application for a badge
  • with your own site capturing the application data
  • applications can then be assessed in the Web app
  • receive notification of an application being reviewed
  • your site handles contacting the earner
  • issue a badge
  • your site handles contacting the earner
  • filter data by system, issuer and program
  • optional admin levels
  • update badge or application data

If you use the BadgeKit Web app, it will call on some of the API endpoints automatically when you interact with the app user interface, for example when you publish a badge. If you aren't using the Web app, you can provide badge admin within your own site. Either way, you will need to use the API in conjunction with your own earner-facing functionality.

Systems, Issuers and Programs

BadgeKit provides the option to build various levels of badge admin into your issuing application. This has been included in the API following our experiences with issuing organizations. These levels are entirely optional - you do not need to use them if your issuing organization does not require them.

Each BadgeKit instance must have at least one system defined in the database - this is the top-level admin organization, for example it could be a city education authority. Within a system, there can be one or more issuers, for example educational or other institutions. Within each issuer, there can be one or more programs, for example a series of connected learning events.

Badges can be associated with a system, issuer or program.

Since these admin levels are built into BadgeKit, you can use them to filter and target your API calls. For example, you could retrieve the active badges for a particular program within a particular issuer, within a particular system and so on.

The BadgeKit API also provides endpoints for retrieving, creating, deleting or updating issuers and programs.

Webhooks

In addition to the API calls you can use to interact with badge data, BadgeKit also sends data to a webhook URL of your choice, so that you can detect and respond to badging events. You can configure a webhook URL within your BadgeKit instance to receive notifications, processing the data BadgeKit sends when such events occur. BadgeKit API will send data to your webhook when the following events occur:

  • a badge is awarded
  • a badge application is reviewed
  • a badge instance is revoked

Like the API calls, the webhook messages are JSON-structured.

Note that when you issue a badge to an earner email address, BadgeKit will not carry out any communication with the earner. Instead, the API sends notification to the webhook - you can then contact the earner in a way that suits your own community.

See also the webhooks page in the API docs.

Authentication

Calls to the BadgeKit API endpoints and webhooks must be signed using a JWT token, with the secret for your BadgeKit instance. See Authorization for further details and the guides in this wiki for examples.

Installation

For a detailed overview of installing the BadgeKit API in conjunction with the BadgeKit app, see the Self-Hosting Guide.

To install and run the BadgeKit API on its own:

  • Clone the code in this repo to your own server.
  • Set the configuration details, e.g.
export DB_HOST=localhost
export DB_NAME=badgekitapi
export DB_PASSWORD=yourpassword
export DB_USER=root
export MASTER_SECRET=yoursecret
export PORT=8080

The master secret is used authenticate communication with your badge admin front-end, which may be the BadgeKit app. If you are using the BadgeKit app, you will need to set the same secret value in the configs for it. You can then source the file using source env_file.

  • Create a database (using the name you set in your config).
  • Migrate the data using bin/db-migrate up from the BadgeKit API root directory.
  • Insert an issuer system entry in your database, e.g. INSERT INTO systems (slug, name) VALUES ('badgekit', 'Your System');

Next Steps

Once you have the BadgeKit API and Web app up and running, you will still need to carry out a few steps - depending on your requirements:

  • configure your webhook
  • you will need this to detect badges being issued and contact your earners
  • list badges on your site
  • accept earner applications on your site
  • forwarding application data to the API
  • issue badges
  • even if you use BadgeKit to approve earner badge applications, you still need to issue the badges (i.e. create badge instances)
  • communicate with your earners
  • BadgeKit will not contact your earners in any way

You can use the following guidance to help figure out which integration steps you might need to carry out:

BadgeKit API + Web app + Assessment

If you plan on using assessment and are using the Web app as well as the API, the following integration steps will be typical:

  • configuring a webhook URL
  • listing badges on your site
  • accepting earner applications and forwarding them to the API
  • detecting the review webhook, contacting the earner regarding the status of their application
  • issuing badges, optionally following user interaction to accept an offered badge
  • detecting the award webhook, optionally contacting the earner to push their badge to a backpack

BadgeKit API + Web app (no assessment)

If your issuer implementation does not feature assessment and you are using the Web app, the following optional integration steps may apply to you:

  • configuring a webhook URL
  • listing badges on your site
  • issuing badges (creating badge instances)
  • detecting the award webhook, optionally contacting the earner to push their badge to a backpack

BadgeKit API only (without Web app admin interface)

If you are using the BadgeKit API but not the admin interface (openbadges-badgekit Web app), the API provides a host of endpoints you can use to complete both badge admin and issuing. For a full reference, see the API docs. The following steps are among the options facilitated by BadgeKit API:

  • adding new badges/ updating badge information
  • forwarding the data from your own badge creation system
  • adding/ managing admin levels issuer and program
  • listing available badges
  • submitting earner applications (with evidence)
  • forwarding from your own application handling system
  • viewing earner applications
  • submitting application reviews
  • forwarding from your own application review system
  • receiving data from the review webhook
  • issuing badges
  • receiving data from the award webhook
  • creating, retrieving and issuing with claim codes
  • creating and managing milestones

Resources

To get started integrating your site with the API, see these guides:

Some more general resources about BadgeKit:

You can see an overview of the API endpoints in the repo, together with request and response samples: https://github.com/mozilla/badgekit-api/blob/master/docs/api-endpoints.md

Help

For support working with BadgeKit or Open Badges, use any of the following channels:

  • Post general questions in our 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) on the #badges channel.
  • Email questions directly to [email protected] and a member of the team will follow-up.
  • Follow or tweet the Open Badges team @OpenBadges.
  • Get involved or submit issues via the GitHub repos - feedback is always appreciated!

Introduction

Tutorials

Docs

Clone this wiki locally