Aestimia API Documentation

Aestimia is a simple application that allows API clients to submit submissions for badges that mentors review, determining whether or not an applicant's evidence satisfies a rubric.

This is the documentation for the Aestimia API, based on commit 7edf6b73d3. For information on installing and configuring Aestimia, see the Github project.

Overview

The API is accessed from /api/.

Unless otherwise noted, all data is sent and received as JSON.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Authentication is done using HTTP Basic Authentication, with the username api and the password set to the API secret.

Sending invalid fields will result in a 422 Unprocessable Entity response, like so:

Status: 422 Unprocessable Entity
{
    "message": "Validation Error",
    "errors": {
      "evidence.0.mediaType": "Validator \"invalid media type\" failed for path mediaType with value `iemage`"
    }
  }

Schemas

Mentor

The mentor model is fairly simple and straightforward.

email
The email address of the mentor. The username portion of the address can be *, in which case the properties of the mentor are applied to anyone with an email address at the given domain.
classifications
An array of strings that determine which submissions the mentor has permission to view.

Submission

The submission model is complex, and contains a number of sub-models.

_id
The unique identifier for the submission, e.g. 519d2036a8318da30e000004. Assigned by the server when a submission is first created.
learner
The email address of the learner who is submitting the application.
criteriaUrl
The URL pointing to the criteria that the learner must be assessed under. This is analogous to the `criteria` property of the Open Badges Assertion Specification.
achievement
An object containing metadata about the award being sought by the learner.
name
The name of the achievement, e.g. Red Badge of Courage.
description
A short description of the achievement.
imageUrl
A URL pointing to an image of the achievement. Must have a square aspect ratio.
cannedResponses
An optional array of strings containing "canned" responses that the mentor must choose from when assessing a learner's work. Its presence indicates that the learner is under 13.
classifications
An array with at least one string in it. A mentor must share at least one classification in common with a submission in order to have permission to view and assess it.
evidence
An array of evidence objects that constitutes the body of information which the learner believes earns them the award.
url
A URL pointing to the evidence.
mediaType

Any one of the following string values:

Value Description
image An image resource capable of being displayed by a modern Web browser.
link Any type of link not covered by the previous categories that a mentor will be directed to.
reflection
A brief reflection from the learner, explaining why they feel it contributes to their fulfillment of the criteria.
flagged
A boolean indicating whether or not the submission has been flagged for offensive content.
onChangeUrl
A webhook URL that will be called via POST request whenever the submission changes or is reviewed. The payload will be JSON with _id equal to the id of the submission that has been changed.
creationDate
The date and time that the submission was created.
rubric
An object containing detailed information, both required and optional, about the criteria that the learner is being evaluated under.
items
An array of objects outlining components of the rubric.
required
A boolean indicating whether or not the item must be fulfilled to earn the award. If any required rubric item isn't satisfied, the learner does not receive the award. At least one rubric item must be required.
text
A description of the rubric item.
reviews
An array of objects representing the assessments mentors have made for this submission, in chronological order. If the array has no items in it, the submission has not yet been reviewed. Otherwise, the most recent review determines whether the learner has satisfied the rubric and should be awarded a badge.
date
The date the review was conducted.
author
The email address of the mentor who conducted the review.
response
A short textual response representing the mentor's reaction to the learner's submission. If the cannedResponses array is non-empty, this must be equivalent to one of its values. Otherwise, this can be any string of text.
satisfiedRubrics
A list of the rubric items that the submission satisfies, indexed by their position in rubric.items, where the first rubric item is 0. If all required rubric items are satisfied, the learner should be awarded a badge.

Examples

A mentor who has permission to view and assess any math-related submissions:

{
  "email": "baz@bar.org",
  "classifications": [
    "math"
  ]
}

A submission that has been submitted, but not reviewed:

{
  "learner": "brian@example.org",
  "criteriaUrl": "http://seriouscat.com/",
  "achievement": {
    "name": "Tropical Koala Badge",
    "description": "Awarded to Tropical Koalas.",
    "imageUrl": "http://labs.toolness.com/catbadge.png"
  },
  "classifications": [
    "science",
    "math"
  ],
  "evidence": [
    {
      "url": "http://seriouscat.com/serious_cat_is_serious.jpg",
      "mediaType": "image",
      "reflection": "This shows how great I did."
    },
    {
      "url": "https://www.wikipedia.org/"
    }
  ],
  "rubric": {
    "items": [
      {
        "required": true,
        "text": "Learner is a chill bro"
      },
      {
        "required": true,
        "text": "Learner isn't a jerk"
      },
      {
        "required": false,
        "text": "Learner can funnel like 80 beers"
      },
      {
        "required": false,
        "text": "Learner can even lift"
      }
    ]
  }
}

The same submission, awarded:

{
  "learner": "brian@example.org",
  "criteriaUrl": "http://seriouscat.com/",
  "achievement": {
    "name": "Tropical Koala Badge",
    "description": "Awarded to Tropical Koalas.",
    "imageUrl": "http://labs.toolness.com/catbadge.png"
  },
  "classifications": [
    "science",
    "math"
  ],
  "evidence": [
    {
      "url": "http://seriouscat.com/serious_cat_is_serious.jpg",
      "mediaType": "image",
      "reflection": "This shows how great I did."
    },
    {
      "url": "https://www.wikipedia.org/"
    }
  ],
  "rubric": {
    "items": [
      {
        "required": true,
        "text": "Learner is a chill bro"
      },
      {
        "required": true,
        "text": "Learner isn't a jerk"
      },
      {
        "required": false,
        "text": "Learner can funnel like 80 beers"
      },
      {
        "required": false,
        "text": "Learner can even lift"
      }
    ]
  },
  "_id": "000000000000000000000001",
  "reviews": [
    {
      "author": "baz@bar.org",
      "response": "cool yo",
      "satisfiedRubrics": [
        0,
        1
      ]
    }
  ]
}

List mentors

GET /api/mentors

This endpoint returns a list of all mentors. There are no parameters.

Example Response

Status: 200 OK
[
  { 
    "email": "foo@bar.org",
    "classifications": [ "math" ]
  }
]

Update a mentor

POST /api/mentor

This endpoint is used to add, change, and remove mentors. If the classifications parameter is not supplied, the mentor is removed. Otherwise, the mentor is given access to view and assess any submissions that have at least one of the mentor's classifications.

Example Input

{
  "email": "foo@bar.org",
  "classifications": ["math"]
}

Example Response

Status: 200 OK
{
  "message": "updated"
}

Create a submission

POST /api/submission

This endpoint creates a submission for assessment.

Example Input

{
  "learner": "brian@example.org",
  "criteriaUrl": "http://seriouscat.com/",
  "achievement": {
    "name": "Tropical Koala Badge",
    "description": "Awarded to Tropical Koalas.",
    "imageUrl": "http://labs.toolness.com/catbadge.png"
  },
  "classifications": [
    "science",
    "math"
  ],
  "evidence": [
    {
      "url": "http://seriouscat.com/serious_cat_is_serious.jpg",
      "mediaType": "image",
      "reflection": "This shows how great I did."
    },
    {
      "url": "https://www.wikipedia.org/"
    }
  ],
  "rubric": {
    "items": [
      {
        "required": true,
        "text": "Learner is a chill bro"
      },
      {
        "required": true,
        "text": "Learner isn't a jerk"
      },
      {
        "required": false,
        "text": "Learner can funnel like 80 beers"
      },
      {
        "required": false,
        "text": "Learner can even lift"
      }
    ]
  }
}

Example Response

Status: 201 Created
{
  "id": "519140258d6230ae0b00000b"
}

Get a submission

GET /api/submissions/:submissionId

This endpoint retrieves an existing submission.

Example Response

Status: 200 OK
{
  "learner": "brian@example.org",
  "criteriaUrl": "http://seriouscat.com/",
  "achievement": {
    "name": "Tropical Koala Badge",
    "description": "Awarded to Tropical Koalas.",
    "imageUrl": "http://labs.toolness.com/catbadge.png"
  },
  "classifications": [
    "science",
    "math"
  ],
  "evidence": [
    {
      "url": "http://seriouscat.com/serious_cat_is_serious.jpg",
      "mediaType": "image",
      "reflection": "This shows how great I did."
    },
    {
      "url": "https://www.wikipedia.org/"
    }
  ],
  "rubric": {
    "items": [
      {
        "required": true,
        "text": "Learner is a chill bro"
      },
      {
        "required": true,
        "text": "Learner isn't a jerk"
      },
      {
        "required": false,
        "text": "Learner can funnel like 80 beers"
      },
      {
        "required": false,
        "text": "Learner can even lift"
      }
    ]
  },
  "_id": "000000000000000000000001",
  "reviews": [
    {
      "author": "baz@bar.org",
      "response": "cool yo",
      "satisfiedRubrics": [
        0,
        1
      ]
    }
  ]
}

List submissions

GET /api/submissions

This endpoint returns a list of all submissions that satisfy a search criteria. Each criteria is submitted as a query string argument.

Currently, the only search criteria is learner, which is the email of a learner whose submissions you'd like to retrieve.

Example Response

Status: 200 OK
[
  {
    "learner": "brian@example.org",
    "criteriaUrl": "http://seriouscat.com/",
    "achievement": {
      "name": "Tropical Koala Badge",
      "description": "Awarded to Tropical Koalas.",
      "imageUrl": "http://labs.toolness.com/catbadge.png"
    },
    "classifications": [
      "science",
      "math"
    ],
    "evidence": [
      {
        "url": "http://seriouscat.com/serious_cat_is_serious.jpg",
        "mediaType": "image",
        "reflection": "This shows how great I did."
      },
      {
        "url": "https://www.wikipedia.org/"
      }
    ],
    "rubric": {
      "items": [
        {
          "required": true,
          "text": "Learner is a chill bro"
        },
        {
          "required": true,
          "text": "Learner isn't a jerk"
        },
        {
          "required": false,
          "text": "Learner can funnel like 80 beers"
        },
        {
          "required": false,
          "text": "Learner can even lift"
        }
      ]
    },
    "_id": "000000000000000000000001",
    "reviews": [
      {
        "author": "baz@bar.org",
        "response": "cool yo",
        "satisfiedRubrics": [
          0,
          1
        ]
      }
    ]
  }
]