ClassDo API

# Getting Started

# Making your first API call

# Generate an API key

To communicate with the GraphQL server, you'll need an API key with the right scopes and permissions.

Firstly, let's follow the steps in this article (opens new window) on ClassDo's Help Center to create an API key.

Note

Please keep the generated API key safe. You should not share this key with anybody or display it on a publicly accessible platform.

# The GraphQL Endpoint

ClassDo API has a single endpoint:

https://api.classdo.com/graphql

The endpoint remains constant for all operations that you perform.

# Communicating with GraphQL

To call the API of the GraphQL server, we need the x-api-key header with the generated API key as the header value.

Furthermore, we will use the POST method to make the request, as we have to provide a JSON-encoded body in the data portion of the request.

The data payload must always contain a string called query.

Let's make our first request with cURL:

In this request, we will retrieve the organisation ID.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: yourapikey" \
  -d "{ \"query\":\"{ viewer { id } }\"}" \
  https://api.classdo.com/graphql
Breaking down the request line-by-line 
query { # 'query' is the root operation
  viewer { # 'viewer' is an implementation of the organisation interface
    id # return the organisation id
  }
}

# Query and Mutation

The two types of allowed operations in ClassDo's GraphQL API are queries and mutations.

Query operations are used for fetching data and this is similar to GET requests for the REST API, while mutation operations are used to mutate data, which is like POST/PATCH/DELETE for the REST API.

All operations follow this schema (opens new window) and you can see all the operations that ClassDo's GraphQL API provides.

# Example of Queries

Let's walk through an example of a query in GraphQL.

The following query does several things:

  • Looks up your rooms in the organisation
  • Finds the 20 most recently created rooms
  • Returns each room's id, name and room members' id.
query GetRooms {
  viewer {
    rooms(input: { first: 20, orderBy: createdAt_DESC }){
      edges {
        node {
          id
          name
          members {
            edges {
              node {
                id
              }
            }
          }
        }
      }
    }
  }
}

Looking at the composition line by line:

  • query GetRooms {

Because we want to read data from the server instead of modifying it, query is the root operation (If you don't specify an operation, query is also the default). We name this operation GetRooms. Naming the operation is optional, but some tools or frameworks requires naming and it's better to name it so that it is easy to understand.

  • viewer {

We want to first fetch the Viewer (opens new window) object. The Viewer object encapsulates the various queries operations (opens new window) in ClassDo's API.

  • rooms(input: { first: 20, orderBy: createdAt_DESC }){

This line means to fetch the Rooms (opens new window) object.

input is RoomsInput (opens new window), which defines the schema for the input argument. It's optional but you can modify your query condition according to this input argument. In this case, it'll get the first 20 data items that are ordered by the most recent creation date.

  • edges {

This line means to fetch the RoomEdge (opens new window) object.

In case you are unfamiliar with the term edge, it is borrowed from the concepts of graph theory. Essentially, the flexibility of GraphQL allows us to specify relationships between different objects, allowing for nesting when writing our query.

In this example, we make use of the connection between rooms and room members to obtain the room members for each of the rooms. You can read more about that in this documentation (opens new window).

  • node {

This line means to fetch the Room (opens new window) object. The following id and name lines mean to fetch id and name fields for the room. To find out the available fields to return, we can take a look at the schema for the Room object.

  • members {

This line means to fetch the RoomMember (opens new window) object associated with the room. Similar to the previous example about retrieving the RoomEdge object, we also fetch the RoomMemberEdge (opens new window) object and its nodes (opens new window) in the following lines.

# Example of Mutations

The following query creates a new room with the name "My First Room" and the description "Test Room".

mutation CreateNewRoom {
  createRoom(data: { name:"My First Room", description:"Test Room" }) {
    id
    name
    members {
      totalCount
      edges{
        node{
          id
        }
      }
    }
  }
}

Looking at the composition line by line:

  • mutation CreateNewRoom {

Similar to query, mutation is the root operation and you can't modify it. We name this mutation CreateNewRoom. As with queries, naming a mutation is optional.

  • createRoom(data: { name: "My First Rooom", description:"Test Room" }){

    • createRoom:

      This is the name of the mutation. You can see the available list of mutations here (opens new window).

    • data: { name: "My First Rooom", description:"Test Room" }:

      These are arguments of the mutation. You can see greater details on the other supported input arguments here (opens new window).

The following lines retrieves essentially 3 fields from the Room (opens new window) object returned by the mutation operation.

  • id: This refers to the id of the room that was created.
  • name: This is the name of the room which was created. It should be "My First Rooom".
  • members: This fetches the RoomMembers (opens new window) object. You can also specify additional input arguments to the members field to specify conditioning, based on the schema here (opens new window).

← Next Steps →