Intro to the GraphQL API

What is GraphQL?

GraphQL is an API query language and a server-side runtime for executing queries by using a type system to define your data. Everything in GraphQL revolves around a schema, which represents all the data in your system and the type of data it is. The Labelbox GraphQL schema contains types which contain fields which contain functions.

Why does Labelbox use GraphQL?

We chose to use GraphQL to structure our API because it provides more flexibility than REST. Here are some advantages GraphQL offers:

Strongly-typed schema

Both the request query and the response are strongly typed. You will know your query is valid because the schema will not allow improperly written schemas.

Hierarchical structure

Each GraphQL query and response takes the shape of a hierarchical set of fields. This makes the queries easy to create and the responses intuitive to read.

Flexibility

With GraphQL you can get all the data you need in one single request allowing for quicker, more precise data retrieval.

Specificity

Unlike in a REST API, a GraphQL response will include only the data you specify in your query.

Strong tooling

Tools like our API explorer allow you to explore the API schema and run queries in your browser.

Root operation types

Our GraphQL API makes use of two operation types, Query and Mutation. These are special because they provide the entry point for every GraphQL query. We encourage you to experiment with these operation types in our API explorer.

Fields, arguments & object types

Fields, arguments, and object types are used to construct the schema. The Query fields perform read-only operations and the Mutation fields perform writes.

The createLabel example below is a Mutation field.

Fields allow you to perform specialized operations within the Query and Mutation root operation types. The createLabel field in the example above requires an argument and targets the Label object type.

Arguments are defined by name and type and serve a variety of purposes. Each field can have zero or more arguments. In the example above, the data: LabelCreateInput argument is required as specified by the (!) symbol.

Object types are the entities in the database that receive the action performed by the field. For the createLabel field, the Label object type is required as specified by the (!) symbol.

Using the API explorer

Navigate to the API explorer by going logging in to app.labelbox.com and clicking on API explorer in the top right dropdown menu.

In the API explorer, run the following query:

query { 
    user { 
        id 
        email 
        role 
        organization { 
            id 
            name } 
        projects { 
            id 
            name 
        } 
    }
}

This query retrieves your own user information. In GraphQL terminology, user is our root object from which we select all of its fields we want to retrieve (id, email, role) and a sub-object: organization. Hovering over the syntax will give more information about each object/field.

The Documentation Explorer to the upper right provides more Schema details; try searching "User" to explore other fields you can select.

Creating parameterized queries

We can use some of the data we just retrieved to construct a more involved query. Copy and paste the project ID into the Query Variables section in the bottom left pane, like so:

{ "project_id" : "<PROJECT ID HERE>" }

In the main text window, run the following:

query byProjects($project_id: ID!) { 
    projects(where: {id_contains: $project_id}) { 
        members { 
            user { 
                email 
                id 
                role 
            } 
        } 
    }
}

This time, we've created a function for our query by naming it byProjects() and assigning it a parameter, $project_id of type ID. In the bottom pane we've tossed our function an argument for project ID. The resulting data is the member info for only the project we specified.