Skip to content

Latest commit

 

History

History
889 lines (732 loc) · 21 KB

assessment.md

File metadata and controls

889 lines (732 loc) · 21 KB
Raw

Assessment

Badges can be issued following assessment of earner applications. Issuers can allow earners to submit applications for badges, forwarding these applications to the API. Reviewers can then assess pending applications, making awarding decisions and submitting their reviews. When a review is submitted, issuers can detect this at their webhook. Typically an issuer will respond to an approved review by offering the earner the badge, creating a badge instance and marking the application as processed using the updating endpoint below.

Assessment therefore involves two objects in BadgeKit API: applications and reviews.

Applications

NAME VALUE
id integer - id from database
slug string
learner email address - earner email
created timestamp
assignedTo string - email address for assigned reviewer
assignedExpiration timestamp - expiry date for assigned reviewer to complete review, after which another reviewer can be assigned
badge badge - badge applied for
processed timestamp - e.g. set when review is submitted or when badge instance is created
evidence array - each evidence item can include: url, mediaType (which can be image or link) and reflection (which is a string)

Reviews

NAME VALUE
id integer - id from database
slug string
author email address - reviewer email
comment string - applicant feedback
reviewItems array - one for each criteria item in the badge; each reviewItem can include: criterionId, satisfied status and comment

Endpoints

  • Retrieve Applications
  • GET /systems/:slug/applications
  • GET /systems/:slug/issuers/:slug/applications
  • GET /systems/:slug/issuers/:slug/programs/:slug/applications
  • GET /systems/:slug/badges/:slug/applications
  • GET /systems/:slug/issuers/:slug/badges/:slug/applications
  • GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications
  • Retrieve a Specific Application
  • GET /systems/:slug/badges/:slug/applications/:slug
  • GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug
  • GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug
  • Submit an Application
  • POST /systems/:slug/badges/:slug/applications
  • POST /systems/:slug/issuers/:slug/badges/:slug/applications
  • POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications
  • Update an Application
  • PUT /systems/:slug/badges/:slug/applications/:slug
  • PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug
  • PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug
  • Delete an Application
  • DELETE /systems/:slug/badges/:slug/applications/:slug
  • DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug
  • DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug
  • Retrieve Application Reviews
  • GET /systems/:slug/badges/:slug/applications/:slug/reviews
  • GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews
  • GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews
  • Retrieve a Specific Review
  • GET /systems/:slug/badges/:slug/applications/:slug/reviews/:slug
  • GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug
  • GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug
  • Submit an Application Review
  • POST /systems/:slug/badges/:slug/applications/:slug/reviews
  • POST /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews
  • POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews
  • Update a Review
  • PUT /systems/:slug/badges/:slug/applications/:slug/reviews/:slug
  • PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug
  • PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug
  • Delete a Review
  • DELETE /systems/:slug/badges/:slug/applications/:slug/reviews/:slug
  • DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug
  • DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug

Retrieve Applications

Retrieve existing applications within a system, issuer or program or for a specific badge.

Expected request

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

Available request parameters

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

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

Expected response

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

{
    "applications": [
        {
            "id": 1,
            "slug": "application-slug",
            "learner": "[email protected]",
            "created": "2014-05-29T18:24:59.000Z",
            "assignedTo": null,
            "assignedExpiration": null,
            "badge": {
                ...
            },
            "processed": null,
            "evidence": [
                {
                    "url": null,
                    "mediaType": null,
                    "reflection": "I did things relevant to the badge..."
                },
                {
                    "url": "http://issuersite.com/uploaded-image.jpg",
                    "mediaType": "image",
                    "reflection": "A picture of my evidence."
                },
                {
                    "url": "http://awebsite.com/evidence.html",
                    "mediaType": "link",
                    "reflection": "My website where I did things."
                }
            ]
        },
        ...
    ],
    "pageData": {
        "page": 1,
        "count": 2,
        "total": 4
    }
}

Applications are returned in order sorted by created date.

pageData is returned when pagination parameters are used.

Response structure

  • applications [ ]
    • id
    • slug
    • learner
    • created
    • assignedTo
    • assignedExpiration
    • badge
    • processed
    • evidence [ ]
      • url
      • mediaType
      • reflection

Potential errors

None

Retrieve a Specific Application

Retrieve the details for a specific application using its slug.

Expected request

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

Expected response

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

{
    "application": 
      {
          "id": 1,
          "slug": "application-slug",
          "learner": "[email protected]",
          "created": "2014-05-29T18:24:59.000Z",
          "assignedTo": null,
          "assignedExpiration": null,
          "badge": {
              ...
          },
          "processed": null,
          "evidence": [
              {
                  "url": null,
                  "mediaType": null,
                  "reflection": "I did things relevant to the badge..."
              },
              {
                  "url": "http://issuersite.com/uploaded-image.jpg",
                  "mediaType": "image",
                  "reflection": "A picture of my evidence."
              },
              {
                  "url": "http://awebsite.com/evidence.html",
                  "mediaType": "link",
                  "reflection": "My website where I did things."
              }
          ]
      },
      ...
  ]
}

Response structure

  • application
    • id
    • slug
    • learner
    • created
    • assignedTo
    • assignedExpiration
    • badge
    • processed
    • evidence [ ]
      • url
      • mediaType
      • reflection

Potential errors

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

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

Submit an Application

Post an earner application for a badge. If you're using the BadgeKit Web app, submitted applications appear there for review.

Expected request

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

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

Parameters Required Description
learner required The email address for the earner applying.
evidence optional Array including evidence items - each item can include reflection, mediaType and url.
assignedTo optional Email of reviewer application is assigned to.
assignedExpiration optional Expiry date for assigned reviewer to complete review.

Expected response

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

{
    "status": "created",
    "application": 
    {
        "id": 1,
        "slug": "abcdef123456",
        "learner": "[email protected]",
        "created": "2014-05-06T12:24:45.000Z",
        "assignedTo": null,
        "assignedExpiration": null,
        "badge": 
        {
            ...
        },

        "processed": null,
        "evidence": 
        [
            {
                "url": "http://awebsite.com/page",
                "mediaType": "link",
                "reflection": "I did great stuff."
            },
            ...
        ]
    }
}

Response structure

  • status
  • application
  • id
  • slug
  • learner
  • created
  • assignedTo
  • assignedExpiration
  • badge
  • processed
  • evidence [ ]
    • url
    • mediaType
    • reflection

Potential Errors

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

  {
    "code": "ValidationError",
    "message": "Could not validate required fields",
    "details": [
      {
        "field": "learner",
        "value": "..."
      },
      ...
    ]
  }

Update an Application

Update an existing application - a typical use of this endpoint would be to mark an application as processed, for example following review and badge issuing.

Expected request

PUT /systems/:slug/badges/:slug/applications/:slug
PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug
PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug

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

Parameters Description
learner The email address for the earner applying.
evidence Array including evidence items - each item can include reflection, mediaType and url.
assignedTo Email of reviewer application is assigned to.
assignedExpiration Expiry date for assigned reviewer to complete review.
processed Timestamp indicating application has been processed.

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",
    "application": 
    {
        "id": 1,
        "slug": "abcdef123456",
        "learner": "[email protected]",
        "created": "2014-05-06T12:24:45.000Z",
        "assignedTo": null,
        "assignedExpiration": null,
        "badge": 
        {
            ...
        },

        "processed": "2014-05-06T12:24:45.000Z",
        "evidence": 
        [
            {
                "url": "http://awebsite.com/page",
                "mediaType": "link",
                "reflection": "I did great stuff."
            }
        ]
    }
}

Response structure

  • status
  • application
  • id
  • slug
  • learner
  • created
  • assignedTo
  • assignedExpiration
  • badge
  • processed
  • evidence [ ]
    • url
    • mediaType
    • reflection

Potential errors

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

  {
    "code": "ValidationError",
    "message": "Could not validate required fields",
    "details": [
      {
        "message": "Invalid email",
        "field": "learner",
        "value": "..."
      },
      ...
    ]
  }

Delete an Application

Delete an existing application.

Expected request

DELETE /systems/:slug/badges/:slug/applications/:slug
DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug
DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug

Expected response

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

{
    "status": "deleted",
    "application": {
        "id": 1,
        "slug": "abcde12345",
        "learner": "[email protected]",
        "created": "2014-05-29T18:24:59.000Z",
        "assignedTo": null,
        "assignedExpiration": null,
        "badge": null,
        "processed": null,
        "evidence": [ ]
    }

}

Potential errors

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

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

Retrieve Application Reviews

Retrieve reviews for specific applications.

Expected request

GET /systems/:slug/badges/:slug/applications/:slug/reviews
GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews
GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews

Available request parameters

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

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

Expected response

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

{
    "reviews": [
        {
            "id": 1,
            "slug": "abcde12345",
            "author": "[email protected]",
            "comment": "fantastic work",
            "reviewItems": [
              {
                "criterionId": 1,
                "satisfied": 1,
                "comment": "perfect"
              },
            ...
            ]
        },
        ...
    ],
    "pageData": {
        "page": 1,
        "count": 2,
        "total": 4
    }
}

pageData is returned when pagination parameters are used.

Response structure

  • reviews [ ]
  • id
  • slug
  • author
  • comment
  • reviewItems [ ]
    • criterionId
    • satisfied
    • comment

Potential errors

None

Retrieve a Specific Review

Retrieve a specific application review.

Expected request

GET /systems/:slug/badges/:slug/applications/:slug/reviews/:slug
GET /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug
GET /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug

Expected response

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

{
    "review":
    {
        "id": 1,
        "slug": "abcde12345",
        "author": "[email protected]",
        "comment": "fantastic work",
        "reviewItems": [
          {
            "criterionId": 1,
            "satisfied": 1,
            "comment": "perfect"
          },
        ...
        ]
    }
}

Response structure

  • reviews
  • id
  • slug
  • author
  • comment
  • reviewItems [ ]
    • criterionId
    • satisfied
    • comment

Potential errors

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

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

Submit an Application Review

Post a review for a specific application.

Expected request

POST /systems/:slug/badges/:slug/applications/:slug/reviews
POST /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews
POST /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews

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

Parameters Required Description
author required Email address of reviewer.
comment optional Feedback for earner.
reviewItems optional Array, each item includes criterionId, satisfied and comment.

Expected response

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

{
    "status": "created",
    "review": {
        "id": 1,
        "slug": "abcde12345",
        "author": "[email protected]",
        "comment": "fantastic work",
        "reviewItems": [
            {
                "criterionId": 1,
                "satisfied": 1,
                "comment": "perfect"
            },
            ...
        ]
    }

}

Response structure

  • status
  • review
  • id
  • slug
  • author
  • comment
  • reviewItems [ ]
    • criterionId
    • satisfied
    • comment

Potential errors

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

  {
    "code": "ValidationError",
    "message": "Could not validate required fields",
    "details": [
      {
        "message": "Invalid email",
        "field": "author",
        "value": "..."
      },
      ...
    ]
  }

Update a Review

Update an existing application review.

Expected request

PUT /systems/:slug/badges/:slug/applications/:slug/reviews/:slug
PUT /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug
PUT /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug

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

Parameters Description
author Email address of reviewer.
comment Feedback for earner.
reviewItems Array, each item includes criterionId, satisfied and comment.

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",
    "review": {
        "id": 1,
        "slug": "abcde12345",
        "author": "[email protected]",
        "comment": "fantastic work",
        "reviewItems": [
            {
                "criterionId": 1,
                "satisfied": 1,
                "comment": "perfect"
            },
            ...
        ]
    }
}

Response structure

  • status
  • review
  • id
  • slug
  • author
  • comment
  • reviewItems [ ]
    • criterionId
    • satisfied
    • comment

Potential errors

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

  {
    "code": "ValidationError",
    "message": "Could not validate required fields",
    "details": [
      {
        "message": "Invalid email",
        "field": "author",
        "value": "..."
      },
      ...
    ]
  }

Delete a Review

Delete an existing application review.

Expected request

DELETE /systems/:slug/badges/:slug/applications/:slug/reviews/:slug
DELETE /systems/:slug/issuers/:slug/badges/:slug/applications/:slug/reviews/:slug
DELETE /systems/:slug/issuers/:slug/programs/:slug/badges/:slug/applications/:slug/reviews/:slug

Expected response

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

{
    "status": "deleted",
    "badge": {
        "id": 1,
        "slug": "abcde12345",
        "author": "[email protected]",
        "comment": "fantastic work",
        "reviewItems": [
            {
                "criterionId": 1,
                "satisfied": 1,
                "comment": "perfect"
            },
            ...
        ]
    }
}

Response structure

  • status
  • review
  • id
  • slug
  • author
  • comment
  • reviewItems [ ]
    • criterionId
    • satisfied
    • comment

Potential errors

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

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