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

Latest commit

 

History

History
337 lines (271 loc) · 8.62 KB

issuing.md

File metadata and controls

337 lines (271 loc) · 8.62 KB
Raw

Issuing

Issuing is the process of awarding a badge to a specific earner. In BadgeKit API, issuing a badge means creating a badge instance. Note that when a review is submitted in which an earner application for a badge is approved, this does not mean that the badge is automatically issued. Issuer sites must use the below API endpoints to issue badges, marking any relevant applications as processed when this occurs. These endpoints also apply to badges issued without the assessment process, for example badges issued directly to earner email addresses or using claim codes.

Badge Instances

NAME VALUE
slug string
email email address - earner email
expires timestamp - optional expiry date
issuedOn timestamp - API will generate
claimCode claim code - if badge is issued using claim code
assertionUrl url - location of issued badge assertion, generated by API
badge badge - API endpoints return badge issued along with instances

Endpoints

  • Retrieve Badge Instances
  • GET /systems/:slug/badges/:slug/instances
  • GET /systems/:slug/issuers/:slug/badges/:slug/instances
  • GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances
  • Retrieve a Specific Instance
  • GET /systems/:slug/instances/:email
  • GET /systems/:slug/issuers/:slug/instances/:email
  • GET /systems/:slug/issuers/:slug/programs/:slug/instances/:email
  • GET /systems/:slug/badges/:slug/instances/:email
  • GET /systems/:slug/issuers/:slug/badges/:slug/instances/:email
  • GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email
  • Create a Badge Instance
  • POST /systems/:slug/badges/:slug/instances
  • POST /systems/:slug/issuers/:slug/badges/:slug/instances
  • POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances
  • Delete an Instance
  • DELETE /systems/:slug/badges/:slug/instances/:email
  • DELETE /systems/:slug/issuers/:slug/badges/:slug/instances/:email
  • DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email

Retrieve Badge Instances

Retrieves all instances for a specific badge within a system, issuer or program.

Expected request

GET /systems/:slug/badges/:slug/instances
GET /systems/:slug/issuers/:slug/badges/:slug/instances
GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances

Available request parameters

  • page: - page of results to return
  • count: - count of results to return per page

e.g. /systems/<slug>/badges/<slug>/instances?count=2&page=1

Expected response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "instances": [
    {
      "slug": "instance-slug",
      "email": "[email protected]",
      "expires": "2014-10-29T10:16:01.000Z",
      "issuedOn": "2014-05-29T10:16:01.000Z",
      "claimCode": "claim-code",
      "assertionUrl": "http://issuersite.com/public/assertions/instance-slug",
      "badge": {
        "id": 1,
        "slug": "badge-slug",
        ...
      }
    },
    ...
  ],
  "pageData": {
    "page": 1,
    "count": 2,
    "total": 4
  }
}

pageData is returned when pagination parameters are used.

Response structure

  • instances [ ]
  • slug
  • email
  • expires
  • issuedOn
  • claimCode
  • assertionUrl
  • badge

Potential errors

None

Retrieve a Specific Instance

Retrieve a specific instance of a badge.

Expected request

GET /systems/:slug/instances/:email
GET /systems/:slug/issuers/:slug/instances/:email
GET /systems/:slug/issuers/:slug/programs/:slug/instances/:email
GET /systems/:slug/badges/:slug/instances/:email
GET /systems/:slug/issuers/:slug/badges/:slug/instances/:email
GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email

You can retrieve instances of badges awarded to a particular email address, for systems, issuers, programs and badges.

Expected response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "instance":
    {
      "slug": "instance-slug",
      "email": "[email protected]",
      "expires": "2014-10-29T10:16:01.000Z",
      "issuedOn": "2014-05-29T10:16:01.000Z",
      "claimCode": "claim-code",
      "assertionUrl": "http://issuersite.com/public/assertions/instance-slug",
      "badge": {
        "id": 1,
        "slug": "badge-slug",
        ...
      }
    }
}

Response structure

  • instance
  • slug
  • email
  • expires
  • issuedOn
  • claimCode
  • assertionUrl
  • badge

Potential errors

  • Instance not found
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "code": "ResourceNotFound",
  "message": "Could not find badgeInstance field: `email`, value: <attempted-email>"
}

Create a Badge Instance

To actually issue (or "award") a badge to an earner in BadgeKit API, you create a badge instance. A badge instance is an awarded badge, issued to a specific earner.

Expected request

POST /systems/:slug/badges/:slug/instances
POST /systems/:slug/issuers/:slug/badges/:slug/instances
POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances

Requests can be sent as application/json, application/x-www-form-urlencoded or multipart/form-data.

Parameters Required Description
email required The email address for the earner the badge is being issued to.
claimCode optional A claim code for the badge.
slug optional Instance slug. (API will generate if not provided.)
issuedOn optional Timestamp representing date issued. (API will generate if not provided.)
expires optional Timestamp representing date instance expires.

Expected response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "status": "created",
  "instance": {
      "slug": "abcdefghi123456789abcdefghi123456789",
      "email": "[email protected]",
      "expires": null,
      "issuedOn": "2014-05-29T10:16:01.654Z",
      "claimCode": "abcde12345",
      "assertionUrl": "http://issuersite.com/public/assertions/abcdefghi123456789abcdefghi123456789",
      "badge": null
  }
}

The assertion URL represents the location of the badge assertion. A badge assertion contains the details of an issued badge. See the latest assertion specification for more information. Claim code is only returned if the badge instance was created using a claim code.

Response structure

  • status
  • instance
  • slug
  • email
  • expires
  • issuedOn
  • claimCode
  • assertionUrl
  • badge

Potential errors

  • Invalid data
  HTTP/1.1 400 Bad Request
  Content-Type: application/json

  {
    "code": "ValidationError",
    "message": "Could not validate required fields",
    "details": [
      {
        "field": "email",
        "value": "..."
      },
      ...
    ]
  }
  • Duplicate entry
  HTTP/1.1 409 Conflict
  Content-Type: application/json

  {
    "code": "ResourceConflict",
    "message": "User <email> has already been awarded badge <badge-slug>",
    "details": {
        "assertionUrl": "http://issuersite.com/public/assertions/abcde..."
        ...
    }
  }

Delete an Instance

Delete a badge instance within a system, issuer or program context.

Expected request

DELETE /systems/:slug/badges/:slug/instances/:email
DELETE /systems/:slug/issuers/:slug/badges/:slug/instances/:email
DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/instances/:email

Expected response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "instance": {
      "slug": "abcdefghi123456789abcdefghi123456789",
      "email": "[email protected]",
      "expires": null,
      "issuedOn": "2014-05-29T10:16:01.654Z",
      "claimCode": "abcde12345",
      "assertionUrl": "http://issuersite.com/public/assertions/abcdefghi123456789abcdefghi123456789",
      "badge": {
        ...
      }
  }
}

Response structure

  • instance
  • slug
  • email
  • expires
  • issuedOn
  • claimCode
  • assertionUrl
  • badge

Potential errors

  • Instance not found
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "code": "ResourceNotFound",
  "message": "Could not find badgeInstance field: `email`, value: <attempted-email>"
}