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)
• /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
• /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)
• /classifications/users/:id?period=day => will return total_count of classifications done by user with id :id 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, 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). And will also return the number of unique_project_contributions the user has contributed to.
  
  • NOTE: cannot search project_contributions and query by project/s or workflow/s

Authorization Policy for /classifications/users/:user_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