Skip to content

Latest commit

 

History

History
69 lines (47 loc) · 3.25 KB

baking_api.md

File metadata and controls

69 lines (47 loc) · 3.25 KB
Raw

Mozilla Hosted Backpack - Badge Baking API

Each awarded badge is represented as an assertion. An assertion is some JSON metadata and a badge image. You can "bake" the assertion data into a badge, meaning that the image has the JSON data embedded into it. See the baking specification for a detailed overview of how baked badges work.

The Mozilla Backpack offers a REST API for baking data into your badge images.

You can alternatively bake badges using the Web interface at: http://bakery.openbadges.org/

You do not need to bake badges when using the Issuer API as it handles baking automatically.

To use the baking API, you need to have your assertions prepared. If you don't have assertions built and stored yet, see these pages:

Baking

The endpoint for baking a badge is /baker. You can make a GET request to the baking service, passing the URL of your badge assertion. The baker will retrieve the badge image file listed as image in the badge class linked to from your assertion JSON. The baker will embed the assertion data into that image and return it to you as a raw data stream. You can then save it as an image file, with the assertion data stored within it.

Earners who use the Mozilla Backpack can upload baked images to their Backpacks and the embedded data will automatically be extracted.

Expected request

GET <backpack-location>/baker

Example request

In a Web browser, a successful call should result in the baked badge being downloaded:

http://backpack.openbadges.org/baker?assertion=http://yoursite.com/badge-assertion.json

In a terminal, a successful call can save the baked badge image locally:

curl http://backpack.openbadges.org/baker?assertion=http://yoursite.com/badge-assertion.json > baked-badge.png

Possible errors

The baking service will perform a HEAD request and a GET request on your badge assertion to ensure validity. Then it will perform a GET request to retrieve the badge image included in the badge class JSON.

You may recieve an error response from the baking sevice for any of the following reasons:

  • your assertion is invalid
  • your assertion could not be reached
  • a request returned an invalid content type
  • your image was unreachable
  • your image was too large (>256kb)

Error responses will have the following structure:

{
    "message": "Error message",
    "stack": "Error detail",
    "code": "error-code",
    "extra": 404
}