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

Home

Jump to bottom
Sue Smith edited this page Apr 18, 2014 · 22 revisions

BadgeKit API

Welcome to the BadgeKit API repo! Issuers can use the BadgeKit tools to aid the process of 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 facilitates processing applications for badges, so that issuers 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.

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 a list of badges (optionally only returning either inactive or active badges)
  • create a new badge
  • update the data for an existing badge
  • retrieve the data for a specific badge
  • delete a badge.

If you use the BadgeKit Web app, it will call on some of the API endpoints when you interact with the app user interface, for example when you publish a badge.

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.

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 provides webhooks 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. Examples include a badge being awarded and a badge application being reviewed. Like the API calls, the webhook messages are JSON-structured.

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.

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.
  • Create a database.
  • Use schema.sql in the BadgeKit API root directory to create the database tables.
  • Insert an issuer system entry in your database, e.g. INSERT INTO systems (slug, name) VALUES ('badgekit', 'Your System');
  • Set the configuration details, e.g.
DB_HOST=localhost
DB_NAME=badgekitapi
DB_PASSWORD=yourpassword
DB_USER=root
MASTER_SECRET=yoursecret
PORT=8080

The database details should match the one you just created. 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.

Resources

To get started with the API, see Using BadgeKit API.

See also the following resources:

We will be adding detailed guides to using the API endpoints and webhooks soon - check back for updates!

You can see an overview of the API endpoints in the repo now: https://github.com/mozilla/badgekit-api/blob/master/docs/api-endpoints.md

If you need additional support working with BadgeKit or Open Badges, use any of the following channels:

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 badges@mozillafoundation.org 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