API

API

Introduction

The primary consumers of the Open Badger API are Webmaker Applications (e.g. Thimble, Popcorn Maker).

Open Badger is based the idea of crediting users for behaviors and offering them badges based on those behaviors. It is inspired by the Badgeville API.

Security Model

The API can be used anonymously, or on behalf of the users of Webmaker Applications. When used on behalf of users, an API request must receive an auth parameter containing a JSON Web Token, signed by a shared secret that the API host and the client have established beforehand.

Requests made on behalf of users must have the prn claim set to a string representing the relevant user's email address in the JWT.

Future Security Considerations

This section describes potential functionality that may be added to Open Badger in the future, and does not reflect the current state of the software.

Like Badgeville, we'll eventually implement a per-behavior rate-limiting mechanism to prevent abuse of the system.

It may be useful for servers to provide browsers with tokens that only allow for certain behaviors (e.g., clicking on a button) to be credited, while reserving the crediting of other behaviors (e.g., making a purchase) for itself, thus preventing certain kinds of abuse. This might be done by associating tags (or categories) with behavior types, and embedding information about what kinds of behaviors can be credited into the JWT as a claim.

Example

Here's an example JWT Claims Set that allows the token bearer to credit foo@bar.org with HYPERLINK and HTML_COMMENT behaviors.

{
  "iss": "https://thimble.webmaker.org",
  "aud": "https://clopenbadger.webmaker.org",
  "prn": "foo@bar.org",
  "exp": 1300819380
}

Note that the above object only represents a JWT Claims Set, and not a full JWT; see Example JWT in the JWT specification for a full example.

Rejection

Any request that is rejected due to insufficient authorization returns a 403 Forbidden status code with a JSON response like the following:

{
  "status": "forbidden",
  "reason": "the user foo@bar.org cannot credit a behavior to baz@bar.org."
}

Data Types

Timestamps

Unless otherwise noted, all timestamps are JSON numeric values representing the number of seconds from 1970-01-01T0:0:0Z UTC until the specified UTC date/time. See RFC 3339 for details regarding date/times in general and UTC in particular.

Shortnames

Each badge and behavior type has a unique, administrator-defined shortname that is used to identify it. A shortname consists only of ASCII alphanumeric characters, underscores, and hyphens. They must also begin with a letter (not an underscore or digit).

Summary

The following endpoints are used by Webmaker Applications:

• GET /v1/badges
• GET /v1/user
• POST /v1/user/mark-all-badges-as-read
• POST /v1/user/behavior/<shortname>/credit

Endpoints

GET /v1/badges

Get information about all existing badge classes.

This is needed by Webmaker Applications to show information about available badges to users. It requires no authorization.

Example

This endpoint returns 200 OK:

{
  "status": "ok",
  "badges": {
    "first-login": {
      "name": "First Login",
      "description": "Like a champion, you logged in, vanquishing all privacy policies and terms of service in your path.",
      "criteria": "Can log into a site that uses Persona for authentication.",
      "image": "https://wiki.mozilla.org/images/b/bb/Merit-badge.png",
      "behaviors": [
        { "name": "logged-in", "score": 1 }
      ],
      "prerequisites": ["some-other-badge"]
    },
    ...
  }
}

description and criteria can contain HTML.

behavior is an array of objects, each object containing the shortname of the behavior and the score for the behavior, which is the amount of times the behavior must be credited before the badge is awarded. If the array is empty, the badge is awarded based entirely on prerequisites.

prerequisites is a list of badge shortnames that are required to earn the badge.

GET /v1/user

Get information on a user's behavior and badge information.

This is needed by Webmaker Applications to display information about earned badges to users. Requires user authorization; users other than email cannot access this endpoint.

Parameters

• auth: The JWT corresponding to the user making the request.
• email: The email of the relevant user.

Example

This endpoint returns 200 OK:

{
  "status": "ok",
  "behaviors": {
    "logged-in": 5
  },
  "badges": {
    "first-login": {
      "issuedOn": 1344816000,
      "assertionUrl": "https://clopenbadger.webmaker.org/afjeo23",
      "isRead": false
    }
  }
}

POST /v1/user/mark-all-badges-as-read

Mark all badges as read.

This is needed by Webmaker Applications. Requires user authorization; users other than email cannot access this endpoint.

Parameters

• auth: The JWT corresponding to the user making the request.
• email: The email of the relevant user.

Examples

This endpoint returns 200 OK:

{"status": "ok"}

POST /v1/user/behavior/<shortname>/credit

Credit a user with a behavior.

This is needed by Webmaker Applications. Requires user authorization; users other than email cannot access this endpoint. Additionally, the claim clopenbadger:creditBehaviors must contain <shortname>.

Parameters

• auth: The JWT corresponding to the user making the request.
• email: The email of the relevant user.

Examples

If no badges are awarded, this endpoint returns 200 OK:

{
  "status": "ok",
  "progress": {
    "fancy-badge": {
      "name": "Fancy Badge",
      "description": "A real fancy badge",
      "image": "http://badges.webmaker.org/badge/image/fancy-badge.png",
      "remaining": {
        "link": 10,
        "comment": 14,
        "image": 4
      }
    },
    ...
}

Or, if badges are awarded, this endpoint returns 201 Created:

{ 
  "status": "awarded",
  "badges": {
    "first-login": {
      "issuedOn": 1344816000,
      "assertionUrl": "https://clopenbadger.webmaker.org/afjeo23",
      "isRead": false
    },
    ...
  },
  "progress": { ... }
}