API v1

Terminology

• Platform The LMS (e.g., Moodle, Canvas, Brightspace, etc.)
• Service This API service
• Tool The peerScholar application

General Info

• This API grants registered Platforms limited access to Tool data.
• Data returned will be within the scope provided by the Platform registration.
• Platform registrations are limited to the specified Service host.

Service Hosts

	Host
Nightly	https://nightly.peerscholar.io
Quality Assurance	https://qa.peerscholar.io
Production	https://app.peerscholar.com

Auth

All communication between the Service and Platforms will be authorized by an asymmetric JWT (RS256) in the Authorization header with the "Bearer" prefix.

Authorization Bearer {JWT}

  "header": {
    "typ": "jwt",
    "alg": "RS256"
  },
  "payload": {
    "iss": url(Tool OR Service Host),
    "aud": url(Tool OR Service Host),
    "iat": date(UTC UNIX Timestamp),
    "exp": date(UTC UNIX Timestamp)
  }

Response Details

• Valid requests will return a JSON payload along with a HTTP 200 response.
• Paged data sets will include a top-level "paging" property that shows the items per page, the current page, and the total number of pages.
• Invalid requests will return a JSON payload containing an error property set to true, an error message that describes the error and the appropriate HTP response code.

Valid Response HTTP 200

{
  "paging": {
    "per_page": "100",
    "current_page": "1",
    "total_pages": "5"
  },
  "data": [
    {
      "id": int(course id),
      "title": string(course title),
      ...
    },
    ...
  ] 
}

Invalid Response HTTP 400|500|etc.

{
  "error": "true",
  "message": string(error details)
}

Paging Parameters
Requests can be paged using query parameters (/endpoint?pp=10&cp=2)

Parameter	Effect
pp	Sets the number of items to include in a single page
cp	Sets the page of results to return

Data Objects

Course Object

Course Object. Describes a course.

{
  "id": int(course id),
  "title": string(course title),
  "nickname": string(course nickname),
  "description": string(course description),
  "code": string(course code),
  "subject": string(course subject),
  "createdDate": timestamp(UNIX timestamp),
  "startDate": timestamp(UNIX timestamp),
  "endDate": timestamp(UNIX timestamp)
}

Course Notification Object

Course Notification Object. Describes a course notification.

{
  "id": int(course id),
  "course_id": string(course id),
  "activity_id": string(activity id),             // null if not applicable
  "account_id": string(account id of the sender), // null if not applicable
  "createdDate": timestamp(UNIX timestamp),
  "startDate": timestamp(UNIX timestamp),
  "endDate": timestamp(UNIX timestamp),
  "content": string(notification text content)
}

Course Membership Object

Course Membership Object. Describes a user's role in a course.

{
  "id": int(membership id),
  "role": string(role title), // Student | Instructor | Grader | Builder
  "account_id": string(account id),
  "accessed": timestamp(UNIX timestamp),
  "status": bool(1 = active; 0 = dropped),
  "enabled": bool(1 = enabled; 0 = disabled),
}

Activity Object

Activity Object. Describes an activity.

{
  "id": int(activity id),
  "course_id": string(course id),
  "title": string(activity title),
  "type": string(activity type), // Standard | Case | Group
  "nickname": string(activity title),
  "description": string(activity description),
  "visible": bool(1 = visible | 0 = hidden),
  "createdDate": timestamp(UNIX timestamp),
  "schedule": array(schedule ids)
}

Schedule Object

Schedule Object. Describes an activity schedule.

{
  "id": int(schedule id),
  "activity_id": int(activity id),
  "phase": string(schedule phase), // Create | Assess | Reflect
  "manual": bool(1 = manual start/stop | 0 = scheduled),
  "startDate": timestamp(UNIX timestamp),
  "endDate": timestamp(UNIX timestamp),
  "order": int(schedule order),
  "enabled": bool(1 = enabled | 0 = disabled)
}

Report Object

Report Object. Describes performance in an activity.

{
  "account_id": int(account id),
  "activity_id": string(activity id),
  ... mixed(multiple fields determined by types param),
}

Courses

Courses

GET /v1/courses

Returns an array of Course Objects associated with a Platform.

{

  "data": [
    {
      "id": int(course id),
      "title": string(course title),
      ...
    },
    ...
  ] 
}

Course

GET /v1/course/{course_id}

Returns a single Course Object.

{
  "data": {
    "id": int(course id),
    "title": string(course title),
    ...
  }
}

Members

GET /v1/course/{course_id}/members

Returns an array of Course Membership Objects objects.

{

  "data": [
    {
      "id": int(membership id),
      "role": string(role title),
      ...
    },
    ...
  ] 
}

Notifications

GET /v1/course/{course_id}/notifications

Returns an array of Course Notification Objects.

{

  "data": [
    {
      "id": int(notification id),
      "course_id": string(course id),
      ...
    },
    ...
  ] 
}

POST /v1/course/{course_id}/notifications

Create a Course Notification Object within the Tool.

{

  "data":
    {
      "course_id": string(course id),
      "startDate": timestamp(UNIX timestamp),
      "endDate": timestamp(UNIX timestamp),
      "content": string(notification text content)
    }
  ] 
}

Activities

Activity

GET /v1/activity/{activity_id}

Returns a single Activity Object.

{

  "data": {
    "id": string(activity id),
    "title": string(activity title),
    ... 
  }
}

Schedule

GET /v1/activity/{activity_id}/schedule

Returns an array of Schedule Objects.

{

  "data": [
    {
      "id": int(schedule id),
      "activity_id": string(activity id),
      ...
    },
    ...
  ] 
}

Reports

GET /v1/activity/{activity_id}/report

Returns an array of Report Objects.
Accepts a "type" query parameter /v1/course/{course_id}/report?incl=[grade_overall,content_create] to determine the values returned in the object.

{

  "data": [
    {
      "account_id": int(account id),
      "activity_id": string(activity id),
      ...
    },
    ...
  ] 
}

Type Param	Return Value
grade_overall	The overall grade for the activity (default)
grade_instuctor	The instructor grade given to the student in the activity
grade_peer_mean	The mean peer grade given to the student in the activity
grade_peer_median	The median peer grade given to the student in the activity
grade_peer_mode	The most common (mode) peer grade given to the student in the activity
grade_self_create	The self assessment grade given by the student during the create phase of the activity
grade_self_reflect	The self assessment grade given by the student during the reflect phase of the activity
content_create	The text content submitted by the student during the create phase
content_revise	The text content submitted by the student during the reflect/revise phase