A front-end dev's reverse-engineering of the Zoo EduAPI endpoints, as used by WildCam (Gorongosa) Lab.
This is only a WIP and will be turned into a proper README-like guide/API documentation once completed.
Please feel free to edit/contribute/correct, especially if you know more about the eldritch magicks of Ruby and can simply read the repo code.
Basic Setup
The Education API follows the standard JSON API 1.0 rules. API requests need to have some Zooniverse/Panoptes authorisation code in their request headers - fortunately, this is easily done using the Panoptes JavaScript client.
Example code, using fetch():
import apiClient from 'panoptes-client/lib/api-client';
import fetch from 'isomorphic-fetch'; //The isomorphic-fetch library will save you headaches when handling IE11. Or use a non-fetch alternative.
fetch(root + assignments, {
method: 'POST',
mode: 'cors',
headers: new Headers({
'Authorization': apiClient.headers.Authorization, //Get your Auth code
'Content-Type': 'application/json'
}),
body: JSON.stringify({ //REMINDER: Transform into a string!
"data": {
"attributes": { "name": "TEST" }
}
})
})
.then(response => response.json())
.then(json => { ...(yadda yadda)... });
While this document was being written, we had a bit of a quirk where certain item key names use - dashes instead of the intended _ underscores.
For example, you might see some Response bodies replying with join-token instead of join_token - join_token is the correct one. Please adjust your code accordingly once this quirk has been fixed.
Programs
A program is a database representation of a curricula associated with a Zooniverse project or many projects. Generally, there are two "types" of programs: Wildcam style and Intro2Astro style. The type is indicated by the custom boolean property on the program resource.
Wildcam style programs have custom: true set, meaning:
Assignments are created by teachers
Assignments on POST, the API:
clones the workflow id given in the payload
creates a new subject set with the subject ids in the payload
links the new subject set to the new workflow
assigns student users to the assignment
Does some Carto DB stuff (TO DO: what Carto DB stuff?)
Intro2Astro style programs have custom: false set, meaning:
Assignments are "auto"-created on the classroom POST
This is done by the front end client via javascript
How to create the assignments are stored arbitrarily in the program's metadata object
Students when joining the classroom get automatically assigned to the assignments
{
"data": [
{
"id": "1",
"type": "programs",
"attributes": {
"slug": "astro-101-with-galaxy-zoo",
"name": "Astro 101 with Galaxy Zoo",
"metadata": {
"cardImage": "home-card-intro-to-astro.jpg",
"assignments": {
"2218": {
"name": "Hubble's Law",
"slug": "srallen086/intro2astro-hubble-testing",
"classifications_target": "10"
},
"3037": {
"name": "Galaxy Zoo 101",
"slug": "srallen086/galaxy-zoo-in-astronomy-101",
"classifications_target": "22"
}
},
"redirectOnJoin": false,
"backgroundImage": "astro-background.jpg"
},
"description": "Materials and tools for engaging introductory astronomy students in real research with Galaxy Zoo.",
"custom": false
}
},
{
"id": "2",
"type": "programs",
"attributes": {
"slug": "wildcam-darien-lab",
"name": "Wildcam Darien Lab",
"metadata": {
"cardImage": "home-card-wildcam-darien.jpg",
"workflowId": "3116",
"redirectOnJoin":true,
"sampleSubjects": ["73437","73438","73434"],
"backgroundImage": ""
},
"description": "A map for exploring camera trap data from the WildCam Darien project.",
"custom": true
}
}, {
"id": "4",
"type": "programs",
"attributes": {
"slug": "wildcam-gorongosa-lab",
"name": "Wildcam Gorongosa Lab",
"metadata": {
"redirect": "https://lab.wildcamgorongosa.org/",
"cardImage": "gorongosa-animals.jpg",
"workflowId": "1549",
"sampleSubjects": ["37763","37755","37767"]
},
"description": "A map for exploring camera trap data from the WildCam Gorongosa project.",
"custom": true
}
}
]
}
The API currently does not support other CRUD actions yet for programs. If a new program needs to be created or a program needs updating, then it'll have to be done via the Rails console.
Teacher Stuff
A Teacher needs to do the following:
Create and manage Classrooms.
Each Classroom:
Has its own metadata. (Name, description, etc)
Has any number of Students.
Has any number of Assignments (if Wildcam style program).
Linked to a Program
Filtered by a Program
Create and manage Assignments within Classrooms if the classroom is linked to a Wildcam style program.
Each Assignment:
Is... basically a Zooniverse workflow? (TBC)
Is... associated with a Zooniverse workflow id? (TBC)
Is associated with a Classroom.
Has its own metadata. (Name, description, etc)
Has any number of Subject ids. (If linked to a Wildcam style program. Used to create the workflow. How Subject ids are selected... now that's the fun part!)
Has any number of Students. (Must be a subset of Students in the Classroom)
Zooniverse Education API
A front-end dev's reverse-engineering of the Zoo EduAPI endpoints, as used by WildCam (Gorongosa) Lab.
This is only a WIP and will be turned into a proper README-like guide/API documentation once completed.
Please feel free to edit/contribute/correct, especially if you know more about the eldritch magicks of Ruby and can simply read the repo code.
Basic Setup
The Education API follows the standard JSON API 1.0 rules. API requests need to have some Zooniverse/Panoptes authorisation code in their request headers - fortunately, this is easily done using the Panoptes JavaScript client.
Example code, using
fetch()
:Example Request header will look like...
WARNING (2017.08.07)
While this document was being written, we had a bit of a quirk where certain item key names use
-
dashes instead of the intended_
underscores.For example, you might see some Response bodies replying with
join-token
instead ofjoin_token
-join_token
is the correct one. Please adjust your code accordingly once this quirk has been fixed.Programs
A program is a database representation of a curricula associated with a Zooniverse project or many projects. Generally, there are two "types" of programs: Wildcam style and Intro2Astro style. The type is indicated by the
custom
boolean property on the program resource.Wildcam style programs have
custom: true
set, meaning:Intro2Astro style programs have
custom: false
set, meaning:Classrooms and Programs relationship
GET programs
Request
GET https://education-api.zooniverse.org/programs
Response (Success)
200 OK
Body:
The API currently does not support other CRUD actions yet for programs. If a new program needs to be created or a program needs updating, then it'll have to be done via the Rails console.
Teacher Stuff
A Teacher needs to do the following:
Get Classrooms
Request
GET https://education-api.zooniverse.org/teachers/classrooms/?program_id=1
Response (Success)
200 OK
Body:
Create Classroom
Request
POST https://education-api.zooniverse.org/teachers/classrooms/
Body:
Response (Success)
201 Created
Body:
Edit Classroom
Request
PUT https://education-api.zooniverse.org/teachers/classrooms/1265
Body:
Response (Success)
204 No Content
Delete Classroom
Request
DELETE https://education-api.zooniverse.org/teachers/classrooms/1288
Response (Success)
204 No Content
Delete Student from Classrom
Request
DELETE https://education-api.zooniverse.org/teachers/classrooms/1265/student_users/4246
Response (Success)
204 No Content
Get Assignments
Request
https://education-api.zooniverse.org/assignments?classroom_id=365
Body:
Create Assignment
Request
Body:
Response
201 Created
Edit Assignment
TBD
Delete Assignment
TBD
Student Stuff
Join Classroom
Request
POST https://education-api.zooniverse.org/students/classrooms/1265/join
Body:
Response (Success)
201 Created
Body:
Response (Error - Already Joined)
422 Unprocessable Entity
Body:
Response (Error - Can't Find Classroom / Invalid Join Token(?))
404 Not Found
Body: a 404 page
Get Assignments
TBD