Courses

Courses are an essential part of the system. Courses hold the general details of a class which binds together the students' grades and the assignments they are given.

The course model

The course model contains all the general information about the courses such as code, name, and most importantly their id which many assignments and student grades reference.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the course.

  • Name
    teacher_id
    Type
    string
    Description

    Unique identifier for the teacher teaching the course
    References public.teacher.id

  • Name
    course_code
    Type
    string
    Description

    Code assigned to the course so it can be related to other courses of the same subject. Some courses can have the same course code if they are the same course. Ex. 2 courses teaching college algebra.

  • Name
    course_name
    Type
    string
    Description

    Name of the course.

  • Name
    course_description
    Type
    string
    Description

    Brief description for the course.

  • Name
    minor_max_grade
    Type
    integer
    Description

    Max grade for the minor assignments of the course based on the assignments it has. Will always be null on creation.

  • Name
    minor_weight_
    Type
    integer
    Description

    The weight of the minor grade in the course.

  • Name
    major_max_grade
    Type
    integer
    Description

    Max grade for the major assignments of the course based on the assignments it has. Will always be null on creation.

  • Name
    major_weight
    Type
    integer
    Description

    The weight of the major grade in the course.

  • Name
    practice_max_grade
    Type
    integer
    Description

    Max grade for the practice assignments of the course based on the assignments it has. Will always be null on creation.

  • Name
    credits
    Type
    integer
    Description

    Credits the course is worth. Usually 1 for full-year, and 0.5 for half the year.

  • Name
    course_level
    Type
    string
    Description

    Level of the course. Can be standard, honors, GT, IB, or AP.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the course was created. Generated automatically at creation in ISO 8601 format.



Adding and changing courses

POST/v1/courses/create

Create a course

This endpoint allows you to add a new course.

Required parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier for the course.

  • Name
    teacher_id
    Type
    string
    Description

    Unique identifier for the teacher teaching the course. References public.teacher.id

  • Name
    course_code
    Type
    string
    Description

    Code assigned to the course so it can be related to other courses of the same subject. Some courses can have the same course code if they are the same course. Ex. 2 courses teaching college algebra.

  • Name
    course_name
    Type
    string
    Description

    Name of the course.

  • Name
    minor_weight_
    Type
    integer
    Description

    The weight of the minor grade in the course.

  • Name
    major_weight
    Type
    integer
    Description

    The weight of the major grade in the course.

  • Name
    credits
    Type
    integer
    Description

    Credits the course is worth. Usually 1 for full-year, and 0.5 for half the year.

  • Name
    course_level
    Type
    string
    Description

    Level of the course. Can be standard, honors, GT, IB, or AP.

Optional parameters

  • Name
    course_description
    Type
    string
    Description

    Brief description for the course.

Request

POST
/v1/courses/create
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.createCourse({
  id: "0215c090-6c68-46ee-932e-47be4c8e4a76",
  teacher_id: "d46a031c-1f3a-4be1-99e3-b4cac4a8dc0d",
  course_code: "MATH101",
  course_name: "Algebra 1",
  minor_weight: 0.6,
  major_weight: 0.4,
  credits: 1,
  course_level: "GT",
  course_description: "An introductory course to algebra."
})

Response

{
  "id": "0215c090-6c68-46ee-932e-47be4c8e4a76",
  "teacher_id": "d46a031c-1f3a-4be1-99e3-b4cac4a8dc0d",
  "course_code": "MATH101",
  "course_name": "Algebra 1",
  "minor_max_grade": null,
  "minor_weight": 0.6,
  "major_max_grade": null,
  "major_weight": 0.4,
  "practice_max_grade": null,
  "credits": 1,
  "course_level": "GT",
  "course_description": "An introductory course to algebra.",
  "created_at": "2024-06-22T12:37:83.912408+00:00",
}
GET/v1/courses/:id

Retrieve a course

This endpoint allows you to retrieve a course by providing the course id. Refer to the list at the top of this page to see which properties are included with course objects.

Request

GET
/v1/courses/0215c090-6c68-46ee-932e-47be4c8e4a76
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.getCourse('0215c090-6c68-46ee-932e-47be4c8e4a76')

Response

{
  "id": "0215c090-6c68-46ee-932e-47be4c8e4a76",
  "teacher_id": "d46a031c-1f3a-4be1-99e3-b4cac4a8dc0d",
  "course_code": "MATH101",
  "course_name": "Algebra 1",
  "minor_max_grade": null,
  "minor_weight": 0.6,
  "major_max_grade": null,
  "major_weight": 0.4,
  "practice_max_grade": null,
  "credits": 1,
  "course_level": "GT",
  "course_description": "An introductory course to algebra.",
  "created_at": "2024-06-22T12:37:83.912408+00:00",
}
GET/v1/courses/students/:id

Retrieve all students in a course

This endpoint returns all students and their grades in a course. The students are sorted by highest grade, then by last name and first name.

Request

GET
/v1/courses/students/0215c090-6c68-46ee-932e-47be4c8e4a76
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.getStudents('0215c090-6c68-46ee-932e-47be4c8e4a76')

Response

{
  "id": "0215c090-6c68-46ee-932e-47be4c8e4a76",
  "students": [
    {
      "student": {
        "id": "627a64c9-645a-491f-a851-b59331248af7",
        "first_name": "Bob",
        "middle_name": "Norman",
        "last_name": "Ross",
        "birthday": "1942-10-29",
        "school": "PHHS",
        "grade_level": 12,
        "created_at": "2024-07-04T11:32:23.976408+00:00"
      },
      "grade": 95
    },
    {
      "student": {
        "id": "f4a1d759-7da9-447a-a013-8698f71867be",
        "first_name": "Tom",
        "middle_name": null,
        "last_name": "Smith",
        "birthday": "1997-11-11",
        "school": "PHHS",
        "grade_level": 11,
        "created_at": "2024-07-04T11:33:72.976408+00:00"
      },
      "grade": 95
    },
    {
      "student": {
        "id": "ba70bdc1-5c51-49e7-947d-988f151d7313",
        "first_name": "John",
        "middle_name": "Stephen",
        "last_name": "Doe",
        "birthday": "1996-12-11",
        "school": "PHHS",
        "grade_level": 12,
        "created_at": "2024-07-04T11:33:97.976408+00:00"
      },
      "grade": 90
    }
  ]
}
PATCH/v1/courses/:id

Update a course

This endpoint allows you to perform an update on a course. The max_grades of the course can't be updated from this endpoint, only from editing assignments connected to the course.

Optional parameters

  • Name
    id
    Type
    string
    Description

    Unique identifier for the course.

  • Name
    teacher_id
    Type
    string
    Description

    Unique identifier for the teacher teaching the course. References public.teacher.id

  • Name
    course_code
    Type
    string
    Description

    Code assigned to the course so it can be related to other courses of the same subject. Some courses can have the same course code if they are the same course. Ex. 2 courses teaching college algebra.

  • Name
    course_name
    Type
    string
    Description

    Name of the course.

  • Name
    course_description
    Type
    string
    Description

    Brief description of the course.

  • Name
    minor_weight_
    Type
    integer
    Description

    The weight of the minor grade in the course.

  • Name
    major_weight
    Type
    integer
    Description

    The weight of the major grade in the course.

  • Name
    credits
    Type
    integer
    Description

    Credits the course is worth. Usually 1 for full-year, and 0.5 for half the year.

  • Name
    course_level
    Type
    string
    Description

    Level of the course. Can be standard, honors, GT, IB, or AP.

Request

PATCH
/v1/courses/0215c090-6c68-46ee-932e-47be4c8e4a76
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.updateCourse("0215c090-6c68-46ee-932e-47be4c8e4a76", {
  id: "c8f9040d-03d3-4675-a3cb-f46ea31406b6",
  teacher_id: "d46a031c-1f3a-4be1-99e3-b4cac4a8dc0d",
  course_code: MATH102,
  course_name: "Algebra 2",
  max_grade: 0,
  
  course_description: "An intermediate level algebra course."
})

Response

{
  "id": "c8f9040d-03d3-4675-a3cb-f46ea31406b6",
  "teacher_id": "d46a031c-1f3a-4be1-99e3-b4cac4a8dc0d",
  "course_code": "MATH102",
  "course_name": "Algebra 2",
  "minor_max_grade": null,
  "minor_weight": 0.6,
  "major_max_grade": null,
  "major_weight": 0.4,
  "practice_max_grade": null,
  "credits": 1,
  "course_level": "GT",
  "course_description": "An intermediate level algebra course.",
  "created_at": "2024-06-22T12:37:83.912408+00:00",
}
DELETE/v1/courses/:id

Delete a course

This endpoint allows you to delete your courses in Protocol. Note: This will permanently delete the course and all its grades.

Request

DELETE
/v1/courses/c8f9040d-03d3-4675-a3cb-f46ea31406b6
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.deleteCourse('c8f9040d-03d3-4675-a3cb-f46ea31406b6')



Statistics and Analytics

GET/v1/courses/average/:id?category=value

Retrieve an average

This endpoint gets the average grade of a course based on all the students in the course rounded to the nearest hundredth or if specified returns the average for a specific grade category(major, minor, practice).

Request

GET
/v1/courses/average/0215c090-6c68-46ee-932e-47be4c8e4a76
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.getAverage('0215c090-6c68-46ee-932e-47be4c8e4a76')

Response

{
  "id": "0215c090-6c68-46ee-932e-47be4c8e4a76",
  "average": 93.33 
}

Request with Type

GET
/v1/courses/average/0215c090-6c68-46ee-932e-47be4c8e4a76?category=major
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.getAverage('0215c090-6c68-46ee-932e-47be4c8e4a76', 'major')

Response with category

{
  "id": "0215c090-6c68-46ee-932e-47be4c8e4a76",
  "average": 90
}

Retrieve top or bottom percentage of students

POST/v1/courses/:percentage/:id?startFrom=value

Update the max grade in the course

Get top or bottom percentage of students and their grade in a course using a given percentage. If the percentage is too small, it will return one student. It requires both a percentage parameter and the startFrom query parameter. The startFrom parameter can be 'TOP' or 'BOTTOM'. Percentages will be rounded to the nearest hundredth when calculating how many students to include.

Request

GET
/v1/courses/percentage/50/0215c090-6c68-46ee-932e-47be4c8e4a76?startFrom=TOP
import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.courses.getAverage('0215c090-6c68-46ee-932e-47be4c8e4a76', 50, 'TOP')

Response

{
  "courseId": "0215c090-6c68-46ee-932e-47be4c8e4a76",
  "students": [
    {
      "student": {
        "id": "627a64c9-645a-491f-a851-b59331248af7",
        "first_name": "Bob",
        "middle_name": "Norman",
        "last_name": "Ross",
        "birthday": "1942-10-29",
        "school": "PHHS",
        "grade_level": 12,
        "created_at": "2024-07-04T11:32:23.976408+00:00"
      },
      "grade": 95
    },
    {
      "student": {
        "id": "f4a1d759-7da9-447a-a013-8698f71867be",
        "first_name": "Tom",
        "middle_name": null,
        "last_name": "Smith",
        "birthday": "1997-11-11",
        "school": "PHHS",
        "grade_level": 11,
        "created_at": "2024-07-04T11:33:72.976408+00:00"
      },
      "grade": 95
    }
  ]
}

Was this page helpful?