Insights, now with GraphQL

A few months back, TokBox announced our Insights Dashboard, a view in the Account Portal for customers to better understand their applications’ video data. At the same time, we opened up an API (in private beta) to programmatically access this data in RESTful fashion along with summaries of individual sessions.

Today we’re pushing a new way to access this data as a public beta using GraphQL. GraphQL is a powerful alternative to the typical REST approach of accessing data over HTTP. It was developed by Facebook in 2012, and open sourced in 2015.

Note that this post is discussing our Insights APIs that obtain video metadataThis does not change how developers access any of TokBox’s core video APIs. With that out of the way, let’s get started.

Typically, REST APIs have different URL endpoints requiring an HTTP request per resource. For each request, there is a response with a fixed and predefined object returned. GraphQL provides a schema of the data and a single endpoint that gives clients the power to ask for exactly what schema fields they need and nothing more. Requests are always sent as an http POST with the fields to be returned specified in the body. The resulting response only contains values corresponding to those fields. The benefit of this is that there are fewer requests made, and only necessary information is transmitted over the wire.

Let’s use a scenario to illustrate this more clearly. Suppose that your team has built an e-learning application in which the instructor shares their screen, but students only publish video from their camera. You, as the application developer, want to create a pie chart showing which browsers are being used to screen share.

In a typical REST API, your requests would look something like this:

  1. List the connections in a given session.
  2. Get an object for each of the returned connection IDs, collecting browser information as you go.
  3. List all the streams in a session.
  4. Get an object for each of the returned Stream IDs, collecting which stream was from a screen share, along with its Connection ID as you go.

Now you can map connection IDs that had a screen share (from the Stream object) to the connection IDs in the Connection object which contains the browser used. Filter for extraneous data, plot your results, and you’re done.

With GraphQL, you construct your query using the GraphiQL Explorer tool and make a single API call:

  1. List connections in a given session, include the connections field. Within the connections’ resource field, include the browser and publishers fields. Within the publishers’ resource field, include the videoType field.

Your request body will look something like this:

query {
  project(projectId: 12345678) {
    sessionData{
      session(sessionId:"your_session_id"){
        meetings{
          resources{
            connections{
              resources{
                browser
                publishers{
                  resources{
                    stream{
                      videoType
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

And the response will match this format:

...
...
"connections": {
  "resources": [
    {
      "browser": "Chrome",
      "publishers": {
        "resources": [
          {
            "stream": {
              "videoType": "camera"
            }
          },
          {
            "stream": {
              "videoType": "screen"
            }
          }
        ]
      }
    },
    {
      "browser": "Chrome",
      "publishers": {
        "resources": [
          {
            "stream": {
              "videoType": "camera"
            }
          }
        ]
      }
    }
  ]
}

As you can see, each object returns only the information requested. The connection lists its browsers and publishers, and each publisher lists their videoType – just like we asked. You can take this single response and create your chart.

For more details on how to get started, check out our developer center guide and the GraphiQL explorer.

One final disclaimer: During the public beta period this API will be free to use. Once we roll it out into general availability, we will introduce pricing for this API. For now our goal is to add more fields to the API and see how customers are using it. Please don’t hesitate to reach out if you have any questions. We look forward to seeing what you build.