# ClassDo API

# Overview

Here are some quick links to get you up and running with the ClassDo API:

  • GraphQL
  • Authentication
  • The GraphQL endpoint
  • Query and Mutation
  • JavaScript library

# GraphQL

GraphQL is one of the data query languages.

GraphQL has many strengths in calling api requests as stated below.

  • Get multiple resources in a single request.
  • Choose the data that you need and reduce traffic.
  • Provide schema typed strongly.

If you want to learn more about GraphQL, you can see details from here.

# Authentication

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

Follow the steps in this article on ClassDo help center to create a token.

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

Curl example:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: yourapikey" \
  -d "{ \"query\":\"{ viewer { id } }\"}" \
  https://api.classdo.com/graphql

# Root endpoint

ClassDo API has a single endpoint:

https://api.classdo.com/graphql

# Query and Mutation

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

Queries operations mean fetching data and this is like GET requests for REST, while mutations operations mean to mutate data like POST/PATCH/DELET.

All operations are following this schema and you can see all operations that ClassDo's Graphql API provides.

# Example of Queries

The following query looks up your rooms, finds the 20 most recent created rooms, and returns each room's id, name and room members id.

query {
  viewer {
    rooms(input: { first: 10, orderBy: createdAt_DESC }){
      edges {
        node {
          id
          name
          members {
            edges {
              node {
                id
              }
            }
          }
        }
      }
    }
  }
}

Looking at the composition line by line:

  • query {

Because we want to read data from the server, not to modify it, query is the root operation. (If you don't specify an operation, query is also the default.)

  • viewer {

This line means to fetch Viewer object.

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

This line means to fetch Rooms object. input is RoomsInput. It's optional but you can modify your query condition according to this input argument. In this case, it'll get first 10 data that are ordered by most recent edit.

  • edges {

This line means to fetch RoomEdge object.

  • node {

This line means to fetch Room object. Following id and name lines mean to fetch id and name field.

  • members {

This line means to fetch RoomMember object.

# Example of Mutations

The following query creates a new room with the name "new room" and the description "test room".

mutation CreateNewRoom {
  createRoom(data:{ name:"new room", description:"test room" }) {
    id
    name
    members {
      totalCount
      edges{
        node{
          id
        }
      }
    }
  }
}

Looking at the composition line by line:

  • mutation CreateNewRoom {

Same as 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. Some tool or framework requires naming and it's better to name it easy for understanding.

  • createRoom(data: { name:"new room", description:"test room" }) {
    • createRoom:

      This is the name of the mutation. You can see available list of mutations here.

    • data: { name:"new room", description:"test room" }:

      These are arguments of the mutation. Details are here.

The rest is the same as query after the 3rd line.

# JavaScript library

You can use JavaScript library to call ClassDo API. Details are here.