API Docs

Main Routes

• /comments
• /classifications
• /classifications/users/:id
• /classifications/user_groups/:id

---

Unauthenticated Routes

/comments

The following are all allowable params for /comments (we also allow combinations of params in order for our users/clients to view more detailed responses depending on what they query). Callout examples and responses can be found here

• /comments : will return total_count of comments of all time
• /comments?start_date=__&end_date=__ : returns total_count of comments between that date range (you can also query by just start_date or by just end_date).
  • Must be in format YYYY-MM-DD
• /comments?period=day : will return total_count of comments of all time and the breakdown of comment counts bucketed by the period (this breakdown lives in data attribute of response).
  • period can either be:
    • day
    • week
    • month
    • year
• /comments?project_id=__: will return total_count of comments for given project_id/s. We can search by multiple projects.
  (Eg. /comments?project_id=1,2. Note that project_ids are separated by ,.)
  NOTE: that when searching by multiple projects, ERAS will not break up counts by project, but rather total it up. (Same thing with user_id/s for counting comments and workflow_id/s for counting classifications)
• /comments?user_id= : will return total_count of comments for given user_id/s. Similar to ?project_id but with users.
  NOTE: this callout by user_id does not require any authorizations. Reasoning behind this is that all comments are viewable in Talk anyway. In this way, we get a simpler implementation.

/classifications

• /classifications => will return total_count of classifications of all time
• /classifications?start_date=&end_date= => returns total_count of classifications between that date range (you can also just have start_date or just have end_date
  • Must be in format YYYY-MM-DD
• /classifications?period=day => will return total_count of classifications of all time and breakdown of classification count bucketed by period. (This breakdown lives in data attribute of response).
  Period only allows day, week, month, year as allowed buckets.
• /classifications?workflow_id= => will return total_count of classifications for given workflow_id/workflow_ids. Can search by multiple workflows.
  (Eg. /classifications?workflow_id=1,2 workflow_ids separated by ,.)
  
  • But note that when searching by multiple workflows, ERAS will not break up counts by workflow but rather total it up..
    
  • For simplicity sake, we do not allow search by BOTH workflow_id and project_id, mainly to save a check to Panoptes to see if workflow/s belong to project/s (i.e. a callout to /classifications?workflow_id=1,2&project_id=3 is NOT valid. Either search by workflow_id or project_id)
• /classifications?project_id= => will return total_count of classifications for given project_id/s. Similar to ?workflow_id but this time with projects.

---

Authenticated Routes (Authorization Header required)

The following routes need an Authorization header when making the request to see if the requesting user has access to query stats via the endpoint.

/classifications/users/:id

• /classifications/users/:id => will return total_count of classifications done by the user
• /classifications/users/:id?start_date=__&end_date=__ => returns total_count of classifications done by that user between that date range (you can also just query by just start_date or just end_date)
  • Must be in format YYYY-MM-DD
• /classifications/users/:id?period=day => will return total_count of classifications done by user with id :id of all time and the breakdown of classification counts bucketed by the period (this breakdown lives in data attribute of response).
  Period can either be day, week, month, or year as allowed buckets.
• /classifications/users/:id?project_id= => will return total_count of classifications done by that user with id :id and given project_id/s
• /classifications/users/:id?workflow_id= => will return total_count of classifications done by that use with id :id and given workflow_id/s
  
  • But note that when searching by multiple workflows/projects, ERAS will not break up counts by workflow/project but rather totalw it up.
• /classifications/users/:id?time_spent=true => will return total time_spent of user classification contributions.
  
  • (Total time spent in seconds the user has spent on classifications)
• /classifications/users/:id?project_contributions=true => will return project_contributions (which is a list of project_ids and counts per project that the user (with id :id) has contributed most to; IN order of most contributed).
  
  • NOTE: cannot search project_contributions and query by project/s or workflow/s
• /classifications/users/:id?project_contributions=true&period=day&order_project_contributions_by=recents => will return project_contributions (which is a list of project_ids and counts per project that the user (with id :id) has most recently to.
  

Authorization Policy for /classifications/users/:id

Fairly simple authorization, the querying user either has to be a

• querying his/her/their own stats
• or a Panoptes admin

/classifications/user_groups/:id

• /classifications/user_groups/:id => will return total_count, time_spent, active_users and project_contributions of classifications done by the user_group
  • Note time_spent is in seconds
• /classifications/user_groups/:id?start_date=__&end_date=__ => will return total_count, time_spent, active_users and project_contributions of classifications done by the user_group between that date range (you can also just query by just start_date or just end_date)
  • Must be in format YYYY-MM-DD
  • Note time_spent is in seconds
• /classifications/user_groups/:id?period=day => will return total_count, time_spent, active_users and project_contributions of classifications done by the user_group and the breakdown of classification counts bucketed by the period (this breakdown lives in data attribute of response).
  
  • Period can either be day, week, month, or year as allowed buckets.
  • Note time_spent is in seconds
• /classifications/user_groups/:id?project_id= => will return total_count, time_spent, active_users of classifications done by that user_group with id :id and given project_id/s
  • Note time_spent is in seconds
  • NOTE: project_contributions is not in response when querying by project/s or workflow/s
• /classifications/user_groups/:id?workflow_id= => will return total_count, time_spent, active_users of classifications done by that user_group with id :id and given workflow_id/s
  
  • But note that when searching by multiple workflows/projects, ERAS will not break up counts by workflow/project but rather totalw it up.
  • Note time_spent is in seconds
  • NOTE: project_contributions is not in response when querying by project/s or workflow/s
• /classifications/user_groups/:id?top_contributors=N => will return total_count, time_spent, active_users and project_contributions as well as the top N top_contributors of user_group classification contributions.
  
  • Note time_spent is in seconds
• /classifications/user_groups/:id?individual_stats_breakdown=true => will return group_member_stats_breakdown (which is a list in descending order (by top contributors) of group members, their individual counts and session times, unique project contributions in descending order of the individual member's project contribution count ).
  
  • Note time_spent is in seconds