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.
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`" } }
The mentor model is fairly simple and straightforward.
*
, in which case the properties of the mentor are
applied to anyone with an email address at the given domain.The submission model is complex, and contains a number of sub-models.
519d2036a8318da30e000004
. Assigned by the server when a submission is first created.Red Badge of Courage
.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. |
_id
equal to the id of the submission that has
been changed.
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 ] } ] }
GET /api/mentors
This endpoint returns a list of all mentors. There are no parameters.
Status: 200 OK
[ { "email": "foo@bar.org", "classifications": [ "math" ] } ]
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.
{ "email": "foo@bar.org", "classifications": ["math"] }
Status: 200 OK
{ "message": "updated" }
POST /api/submission
This endpoint creates a submission for assessment.
{ "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" } ] } }
Status: 201 Created
{ "id": "519140258d6230ae0b00000b" }
GET /api/submissions/:submissionId
This endpoint retrieves an existing submission.
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 ] } ] }
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.
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 ] } ] } ]