Groups

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

The group model

The group model contains all the general information about the groups 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 group.
Name
owners
Type
string[]
Description
Array containing ids for the owners of the group. Owners can only be admins and teachers.
Name
members
Type
string[]
Description
Array containing ids for the members of the group. Member can be admins, teachers, or students.
Name
name
Type
string
Description
Name of the group.
Name
saved_tags
Type
object
Description
object containing tags saved for this group to easily be used in posts, with a max limit of 10. The object has a key that should be the tag name and a value that should be tag color.
Name
created_at
Type
timestamp
Description
Timestamp of when the group was created. Generated automatically at creation in ISO 8601 format.

POST/v1/groups/create

Create a group

This endpoint allows you to create a new group.

Required parameters

Name
owners
Type
string[]
Description
Array containing ids for the owners of the group. Owners can only be admins and teachers.

Optional parameters

Name
id
Type
string
Description
Unique identifier for the group. Generated readomly by default
Name
members
Type
string[]
Description
Array containing ids for the members of the group. Members can be admins, teachers, or students. Will be an empty array by default
Name
name
Type
string
Description
Name of the group.
Name
saved_tags
Type
object
Description
object containing tags saved for this group to easily be used in posts, with a max limit of 10. The object has a key that should be the tag name and a value that should be tag color. Will be an empty json by default.
Name
created_at
Type
timestamp
Description
Timestamp of when the group was created. Generated automatically at creation in ISO 8601 format.

Request

POST

/v1/groups/create

import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.groups.createGroup({
  owners: ["5c44a3a4-3fb3-4f14-9eb8-eb716a807922"],
  members: ["627a64c9-645a-491f-a851-b59331248af7"]
  name: "Name of Group"
})

Response

{
  "id": "5ec13e32-3fa6-4f4b-94a0-af016e34b331",
  "owners": ["5c44a3a4-3fb3-4f14-9eb8-eb716a807922"],
  "members": ["627a64c9-645a-491f-a851-b59331248af7"],
  "name": "Name of Group",
  "saved_tags": {},
  "created_at": "2024-06-22T12:37:83.912408+00:00"
}

GET/v1/groups/:id

Retrieve a group

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

Request

GET

/v1/groups/5ec13e32-3fa6-4f4b-94a0-af016e34b331

import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.groups.getGroup('5ec13e32-3fa6-4f4b-94a0-af016e34b331')

Response

{
  "id": "5ec13e32-3fa6-4f4b-94a0-af016e34b331",
  "owners": ["5c44a3a4-3fb3-4f14-9eb8-eb716a807922"],
  "members": ["627a64c9-645a-491f-a851-b59331248af7"],
  "name": "Name of Group",
  "saved_tags": {},
  "created_at": "2024-06-22T12:37:83.912408+00:00"
}

GET/v1/groups/owners/:id

Retrieve all owners of a group

This endpoint retrieves all owners of a group in an array given the group id as a route parameter.

Request

GET

/v1/groups/owners/5ec13e32-3fa6-4f4b-94a0-af016e34b331

import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.groups.getOwners("5ec13e32-3fa6-4f4b-94a0-af016e34b331")

Response

[
  {
    "id": "5c44a3a4-3fb3-4f14-9eb8-eb716a807922",
    "first_name": "Joe",
    "middle_name": "Morgan",
    "last_name": "Richards",
    "birthday": "1993-04-29",
    "school": "PHMS",
    "created_at": "2024-06-22T13:15:57.375619+00:00"
  }
]

GET/v1/groups/members/:id

Retrieve all members of a group

This endpoint retrieves all members of a group in an array given the group id as a route parameter.

Request

GET

/v1/groups/members/5ec13e32-3fa6-4f4b-94a0-af016e34b331

import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.groups.getMembers("5ec13e32-3fa6-4f4b-94a0-af016e34b331")

Response

[
  {
    "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"
  }
]

PATCH/v1/groups/:id

Update a group

This endpoint allows you to perform an update on a group provided the group id as a route parameter. The id and created_at properties can't be changed.

Optional parameters

Name
owners
Type
string[]
Description
Array containing ids for the owners of the group. Owners can only be admins and teachers.
Name
members
Type
string[]
Description
Array containing ids for the members of the group. Members can be admins, teachers, or students. Will be an empty array by default
Name
name
Type
string
Description
Name of the group.
Name
saved_tags
Type
object
Description
object containing tags saved for this group to easily be used in posts, with a max limit of 10. The object has a key that should be the tag name and a value that should be tag color. Will be an empty json by default.

Request

PATCH

/v1/groups/5ec13e32-3fa6-4f4b-94a0-af016e34b331

import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.groups.updateGroup("5ec13e32-3fa6-4f4b-94a0-af016e34b331", {
  name: "New Name of Group"
})

Response

{
  "id": "5ec13e32-3fa6-4f4b-94a0-af016e34b331",
  "owners": ["5c44a3a4-3fb3-4f14-9eb8-eb716a807922"],
  "members": [],
  "name": "New Name of Group",
  "saved_tags": {},
  "created_at": "2024-06-22T12:37:83.912408+00:00"
}

DELETE/v1/delete/groups/:id

Delete a group

This endpoint allows you to delete a group given the group id. Note: This will permanently delete the group.

Request

DELETE

/v1/groups/5ec13e32-3fa6-4f4b-94a0-af016e34b331

import ApiClient from '@example/protocol-api'

const client = new ApiClient(token)

await client.groups.deleteGroup('5ec13e32-3fa6-4f4b-94a0-af016e34b331')