Skip to content

badges.md

Latest commit

 

History

History
877 lines (787 loc) · 22.1 KB

badges.md

File metadata and controls

877 lines (787 loc) · 22.1 KB
Raw

Badges

A badge represents the generic data for an earnable badge (not an awarded badge, which is a badge instance). Badges can be published or archived. Each badge can belong to a system, issuer or program.

NAME VALUE
id integer - ID from database entry.
slug string - Used to identify badge in API endpoints (auto-generated).
name string - Display name.
strapline string - Short tagline description.
earnerDescription string - Description for potential earners.
consumerDescription string - Description for viewers of badge e.g. college admin or employer.
issuerUrl string
rubricUrl string - Link to supporting material.
timeValue integer - Time estimate for earner to complete badge.
timeUnits enum - Can be minutes, hours, days or weeks.
evidenceType enum - Can be URL, Text, Photo, Video or Sound.
limit integer - Limit for number of people who can earn the badge.
unique boolean - True if the same earner can only earn the badge once.
created timestamp
imageUrl string - Badge display image.
type string - Badges can be organized by type and category.
archived boolean - Archived badges can no longer be earned.
system integer - System is represented by ID in database - system details are returned from API endpoints as nested JSON.
issuer integer - Isuser is represented by ID in database - issuer details are returned from API endpoints as nested JSON.
program integer - Program is represented by ID in database - program details are returned from API endpoints as nested JSON.
criteriaUrl string - Link to criteria material.
criteria array - Each item includes id, description, required status and note.
categories array - See above for related type field.
tags array- Tags can be used to aid search and discovery of badges.
milestones array - A milestone badge is awarded when a set of other badges is earned.

Endpoints

  • Retrieve Badge List
  • GET /systems/<slug>/badges
  • GET /systems/<slug>/issuers/<slug>/badges
  • GET /systems/<slug>/issuers/<slug>/programs/<slug>/badges
  • Retrieve Specific Badge
  • GET /systems/<slug>/badges/<slug>
  • GET /systems/<slug>/issuers/<slug>/badges/<slug>
  • GET /systems/<slug>/issuers/<slug>/programs/<slug>
  • Create New Badge
  • POST /systems/<slug>/badges
  • POST /systems/<slug>/issuers/<slug>/badges
  • POST / systems/<slug>/issuers/<slug>/programs/<slug>
  • Update a Badge
  • PUT /systems/<slug>/badges/<slug>
  • PUT /systems/<slug>/issuers/<slug>/badges/<slug>
  • PUT /systems/<slug>/issuers/<slug>/programs/<slug>/badges/<slug>
  • Delete a Badge
  • DELETE /systems/<slug>/badges/<slug>
  • DELETE /systems/<slug>/issuers/<slug>/badges/<slug>
  • DELETE /systems/<slug>/issuers/<slug>/programs/<slug>/badges/<slug>
  • Retrieve Public Badge Class List
  • GET /public/badges

Retrieve Badge List

Retrieves badges, filtered by system, issuer or program.

Expected request

GET /systems/:systemSlug/badges
GET /systems/:systemSlug/issuers/:issuerSlug/badges
GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges

Available request parameters

  • archived: [true|false|any] (optional) - Whether to include archived badges.
    • true will return only archived badges
    • false (default) will return only unarchived badges
    • any will return badges regardless of archived status
  • page: - page of results to return
  • count: - count of results to return per page

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

Expected response

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

{
  "badges": [
    {
      "id": 1,
      "slug": "badge-slug",
      "name": "Badge Name",
      "strapline": "Badge strapline.",
      "earnerDescription": "Badge description for potential earners.",
      "consumerDescription": "Badge description for interested consumers.",
      "issuerUrl": "http://issuersite.com",
      "rubricUrl": "http://issuersite.com/rubric",
      "timeValue": 0,
      "timeUnits": "minutes",
      "evidenceType": "URL",
      "limit": 5,
      "unique": false,
      "created": "2014-05-21T19:22:09.000Z",
      "imageUrl": "http://issuersite.com/badge.png",
      "type": "badge type",
      "archived": false,
      "system": {
          "id": 1,
          "slug": "system-slug",
          "url": "http://systemsite.com",
          "name": "System Name",
          "email": "admin@systemsite.com",
          "imageUrl": "http://systemsite.com/image.jpg",
          "issuers": [ ]
      },
      "issuer": {
          "id": 1,
          "slug": "issuer-slug",
          "url": "http://issuersite.com",
          "name": "Issuer Name",
          "description": "Issuer description.",
          "email": "admin@issuersite.com",
          "imageUrl": "http://issuersite.com/image.jpg",
          "programs": [ ]
      },
      "program": {
          "id": 1,
          "slug": "program-slug",
          "url": "http://programsite.com",
          "name": "Program Name",
          "description": "Program description.",
          "email": "admin@programsite.com",
          "imageUrl": "http://programsite.com/image.jpg"
      },
      "criteriaUrl": "http://issuersite.com/criteria",
      "criteria": [
          {
              "id": 1, 
              "description": "Criteria description.",
              "required": true,
              "note": "Note about criteria for assessor."
          },
          ...
      ],
      "categories": [ ],
      "tags": [ ],
      "milestones": [ ]
    },
    ...
  ],
  "pageData": {
    "page": 1,
    "count": 2,
    "total": 4
  }
}

pageData is returned when pagination parameters are used.

Response structure

  • badges [ ]
    • id
    • slug
    • name
    • strapline
    • earnerDescription
    • consumerDescription
    • issuerUrl
    • rubricUrl
    • timeValue
    • timeUnits
    • evidenceType
    • limit
    • unique
    • created
    • imageUrl
    • type
    • archived
    • system
      • id
      • slug
      • url
      • name
      • email
      • imageUrl
      • issuers [ ]
    • issuer
      • id
      • slug
      • url
      • name
      • description
      • email
      • imageUrl
      • programs [ ]
    • program
      • id
      • slug
      • url
      • name
      • description
      • email
      • imageUrl
    • criteriaUrl
    • criteria [ ]
      • id
      • description
      • required
      • note
    • categories [ ]
    • tags [ ]
    • milestones [ ]

Potential errors

None

Retrieve Specific Badge

Retrieves a specific badge using its slug.

Expected request

GET /systems/:systemSlug/badges/:badgeSlug
GET /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug
GET /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug

Expected response

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

{
  "badge": {
    "id": 1,
    "slug": "badge-slug",
    "name": "Badge Name",
    "strapline": "Badge strapline.",
    "earnerDescription": "Badge description for potential earners.",
    "consumerDescription": "Badge description for consumers.",
    "issuerUrl": "http://issuersite.com",
    "rubricUrl": "http://issuersite.com/rubric",
    "timeValue": 10,
    "timeUnits": "minutes",
    "evidenceType": "URL",
    "limit": 5,
    "unique": false,
    "created": "2014-05-21T19:22:09.000Z",
    "imageUrl": "http://issuersite.com/badge.png",
    "type": "badge type",
    "archived": false,
    "system": {
      "id": 1,
      "slug": "system-slug",
      "url": "http://systemsite.com",
      "name": "System Name",
      "email": "admin@systemsite.com",
      "imageUrl": "http://systemsite.com/image.jpg",
      "issuers": [ ]
    },
    "issuer": {
      "id": 1,
      "slug": "issuer-slug",
      "url": "http://issuersite.com",
      "name": "Issuer Name",
      "description": "Issuer description.",
      "email": "admin@issuersite.com",
      "imageUrl": "http://issuersite.com/image.jpg",
      "programs": [ ]
    },
    "program": {
      "id": 1,
      "slug": "program-slug",
      "url": "http://programsite.com",
      "name": "Program Name",
      "description": "Program description.",
      "email": "admin@programsite.com",
      "imageUrl": "http://programsite.com/image.jpg"
    },
    "criteriaUrl": "http://issuersite.com/criteria",
    "criteria": [
      {
        "id": 1,
        "description": "criteria description",
        "required": 1,
        "note": "note for assessor"
      },
      ...
    ],
    "categories": [ ],
    "tags": [ ],
    "milestones": [ ]
  }
}

Response structure

  • badge
    • id
    • slug
    • name
    • strapline
    • earnerDescription
    • consumerDescription
    • issuerUrl
    • rubricUrl
    • timeValue
    • timeUnits
    • evidenceType
    • limit
    • unique
    • created
    • imageUrl
    • type
    • archived
    • system
      • id
      • slug
      • url
      • name
      • email
      • imageUrl
      • issuers [ ]
    • issuer
      • id
      • slug
      • url
      • name
      • description
      • email
      • imageUrl
      • programs [ ]
    • program
      • id
      • slug
      • url
      • name
      • description
      • email
      • imageUrl
    • criteriaUrl
    • criteria [ ]
      • id
      • description
      • required
      • note
    • categories [ ]
    • tags [ ]
    • milestones [ ]

Potential errors

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

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

Create New Badge

Creates a new badge in a system, issuer or program (or updates an existing badge).

Expected request

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

POST /systems/:systemSlug/badges 
POST /systems/:systemSlug/issuers/:issuerSlug/badges 
POST /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges
Parameters Required Description
name required Name of the badge. Maximum 255 characters.
image OR imageUrl required Image for the program. Should be either multipart data or a URL.
unique required Boolean indicator of whether an earner can earn the badge only once.
criteriaUrl required Link to badge criteria.
earnerDescription required Description of the badge for potential earners.
consumerDescription required Description of the badge for consumers viewing it.
strapline optional Short tagline style description of the badge. Maximum 140 characters.
issuerUrl optional URL for badge issuer.
rubricUrl optional Link to any rubric material associated with the badge.
timeValue optional Badges can be associated with a time limit for earning.
timeUnits optional Time values can be expressed as minutes, hours, days or weeks.
evidenceType optional Type of evidence accepted (can be URL, Text, Photo, Video or Sound)
limit optional Badges can be awarded to a fixed maximum number of earners.
archived optional Boolean indicating archived status for badge.
criteria optional Array of criteria items - each criteria should include description and required status plus optional note for badge reviewers.
type required Short string representing badge type. Maximum 255 characters.
categories optional Array of category names for the badge.
tags optional Array of tag names for the badge.
milestones optional Array of milestones.

Expected response

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

{
  "status": "created",
  "badge": {
    "id": 1,
    "slug": "badge-slug",
    "name": "Badge Name",
    "strapline": "Badge strapline.",
    "earnerDescription": "Badge description for potential earners.",
    "consumerDescription": "Badge description for consumers.",
    "issuerUrl": "http://issuersite.com",
    "rubricUrl": "http://issuersite.com/rubric",
    "timeValue": 10,
    "timeUnits": "minutes",
    "evidenceType": "URL",
    "limit": 5,
    "unique": false,
    "created": "2014-05-21T19:22:09.000Z",
    "imageUrl": "http://issuersite.com/badge.png",
    "type": "badge type",
    "archived": false,
    "system": {
      "id": 1,
      "slug": "system-slug",
      "url": "http://systemsite.com",
      "name": "System Name",
      "email": "admin@systemsite.com",
      "imageUrl": "http://systemsite.com/image.jpg",
      "issuers": [ ]
    },
    "issuer": {
      "id": 1,
      "slug": "issuer-slug",
      "url": "http://issuersite.com",
      "name": "Issuer Name",
      "description": "Issuer description.",
      "email": "admin@issuersite.com",
      "imageUrl": "http://issuersite.com/image.jpg",
      "programs": [ ]
    },
    "program": {
      "id": 1,
      "slug": "program-slug",
      "url": "http://programsite.com",
      "name": "Program Name",
      "description": "Program description.",
      "email": "admin@programsite.com",
      "imageUrl": "http://programsite.com/image.jpg"
    },
    "criteriaUrl": "http://issuersite.com/criteria",
    "criteria": [
      {
        "id": 1,
        "description": "criteria description",
        "required": 1,
        "note": "note for assessor"
      },
      ...
    ],
    "categories": [ ],
    "tags": [ ],
    "milestones": [ ]
  }
}

Response structure

  • status
  • badge
    • id
    • slug
    • name
    • strapline
    • earnerDescription
    • consumerDescription
    • issuerUrl
    • rubricUrl
    • timeValue
    • timeUnits
    • evidenceType
    • limit
    • unique
    • created
    • imageUrl
    • type
    • archived
    • system
      • id
      • slug
      • url
      • name
      • email
      • imageUrl
      • issuers [ ]
    • issuer
      • id
      • slug
      • url
      • name
      • description
      • email
      • imageUrl
      • programs [ ]
    • program
      • id
      • slug
      • url
      • name
      • description
      • email
      • imageUrl
    • criteriaUrl
    • criteria [ ]
      • id
      • description
      • required
      • note
    • categories [ ]
    • tags [ ]
    • milestones [ ]

Potential errors

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

  {
    "code": "ValidationError",
    "message": "Could not validate required fields",
    "details": [
      {
        "message": "String is not in range",
        "field": "name",
        "value": "..."
      },
      ...
    ]
  }

Update a Badge

Updates an existing badge.

Expected request

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

PUT /systems/:systemSlug/badges/:badgeSlug HTTP/1.1
PUT /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug HTTP/1.1
PUT /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug HTTP/1.1
Parameters Description
name Name of the badge. Maximum 255 characters.
image OR imageUrl Image for the program. Should be either multipart data or a URL.
unique Boolean indicator of whether an earner can earn the badge only once.
criteriaUrl Link to badge criteria.
earnerDescription Description of the badge for potential earners.
consumerDescription Description of the badge for consumers viewing it.
strapline Short tagline style description of the badge. Maximum 140 characters.
issuerUrl URL for badge issuer.
rubricUrl Link to any rubric material associated with the badge.
timeValue Badges can be associated with a time limit for earning.
timeUnits Time values can be expressed as minutes, hours, days or weeks.
evidenceType Type of evidence accepted (can be URL, Text, Photo, Video or Sound)
limit Badges can be awarded to a fixed maximum number of earners.
archived Boolean indicating archived status for badge.
criteria Array of criteria items - each criteria should include description and required status plus optional note for badge reviewers.
type Short string representing badge type. Maximum 255 characters.
categories Array of category names for the badge.
tags Array of tag names for the badge.
milestones Array of milestones.

You only have to pass in the fields you are updating. Any fields that are not represented will be left unchanged.

Expected response

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

{
  "status": "updated",
  "badge": {
    "id": 1,
    "slug": "badge-slug",
    "name": "Badge Name",
    "strapline": "Badge strapline.",
    "earnerDescription": "Badge description for potential earners.",
    "consumerDescription": "Badge description for consumers.",
    "issuerUrl": "http://issuersite.com",
    "rubricUrl": "http://issuersite.com/rubric",
    "timeValue": 10,
    "timeUnits": "minutes",
    "evidenceType": "URL",
    "limit": 5,
    "unique": false,
    "created": "2014-05-21T19:22:09.000Z",
    "imageUrl": "http://issuersite.com/badge.png",
    "type": "badge type",
    "archived": false,
    "system": {
      "id": 1,
      "slug": "system-slug",
      "url": "http://systemsite.com",
      "name": "System Name",
      "email": "admin@systemsite.com",
      "imageUrl": "http://systemsite.com/image.jpg",
      "issuers": [ ]
    },
    "issuer": {
      "id": 1,
      "slug": "issuer-slug",
      "url": "http://issuersite.com",
      "name": "Issuer Name",
      "description": "Issuer description.",
      "email": "admin@issuersite.com",
      "imageUrl": "http://issuersite.com/image.jpg",
      "programs": [ ]
    },
    "program": {
      "id": 1,
      "slug": "program-slug",
      "url": "http://programsite.com",
      "name": "Program Name",
      "description": "Program description.",
      "email": "admin@programsite.com",
      "imageUrl": "http://programsite.com/image.jpg"
    },
    "criteriaUrl": "http://issuersite.com/criteria",
    "criteria": [
      {
        "id": 1,
        "description": "criteria description",
        "required": 1,
        "note": "note for assessor"
      },
      ...
    ],
    "categories": [ ],
    "tags": [ ],
    "milestones": [ ]
  }
}

Response structure

  • status
  • badge
    • id
    • slug
    • name
    • strapline
    • earnerDescription
    • consumerDescription
    • issuerUrl
    • rubricUrl
    • timeValue
    • timeUnits
    • evidenceType
    • limit
    • unique
    • created
    • imageUrl
    • type
    • archived
    • system
      • id
      • slug
      • url
      • name
      • email
      • imageUrl
      • issuers [ ]
    • issuer
      • id
      • slug
      • url
      • name
      • description
      • email
      • imageUrl
      • programs [ ]
    • program
      • id
      • slug
      • url
      • name
      • description
      • email
      • imageUrl
    • criteriaUrl
    • criteria [ ]
      • id
      • description
      • required
      • note
    • categories [ ]
    • tags [ ]
    • milestones [ ]

Potential errors

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

  {
    "code": "ValidationError",
    "message": "Could not validate required fields",
    "details": [
      {
        "message": "String is not in range",
        "field": "name",
        "value": "..."
      },
      ...
    ]
  }
  • Badge not found
  HTTP/1.1 404 Not Found
  Content-Type: application/json

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

Delete a Badge

Deletes an existing badge.

Expected request

DELETE /systems/:systemSlug/badges/:badgeSlug HTTP/1.1
DELETE /systems/:systemSlug/issuers/:issuerSlug/badges/:badgeSlug HTTP/1.1
DELETE /systems/:systemSlug/issuers/:issuerSlug/programs/:programSlug/badges/:badgeSlug HTTP/1.1

Expected response

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

{
  "status": "deleted",
  "badge": {
    "id": 1,
    "slug": "badge-slug",
    "name": "Badge Name",
    "strapline": "Badge strapline.",
    "earnerDescription": "Badge description for potential earners.",
    "consumerDescription": "Badge description for consumers.",
    "issuerUrl": "http://issuersite.com",
    "rubricUrl": "http://issuersite.com/rubric",
    "timeValue": 10,
    "timeUnits": "minutes",
    "evidenceType": "URL",
    "limit": 5,
    "unique": false,
    "created": "2014-05-21T19:22:09.000Z",
    "imageUrl": "http://issuersite.com/badge.png",
    "type": "badge type",
    "archived": false,
    "criteriaUrl": "http://issuersite.com/criteria",
    "criteria": [ ],
    "categories": [ ],
    "tags": [ ],
    "milestones": [ ]
  }
}

Potential errors

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

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

Retrieve Public Badge Class List

Retrieves list of public badge classes - API returns URL for each badge class.

The authorization header is not required for this endpoint.

Expected request

GET /public/badges

Expected response

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

{
 "badgelist": [
 {
  "location": "http://issuersite.com/public/systems/system-slug/badges/badge-slug"
 },
 {
  "location": "http://issuersite.com/public/systems/system-slug/issuers/issuer-slug/programs/program-slug/badges/badge-slug"
 },
 ...
 ]
}

Response structure

  • badgelist [ ]
    • location

Potential errors

None