Using the GraphQL Playground

You can run API calls on actual Brikl data using the GraphQL Playground, a development environment that runs in your browser and includes docs, syntax highlighting, and validation errors.

About the GraphQL Playground

The GraphQL Playground is the perfect place to get started with API calls. It runs in your browser and has all tools you need to test and learn how GraphQL operations work.

Using the GraphQL Playground

To use the GraphQL Playground, you'll need to provide a Personal Access Token (PAT) and your Shop ID as HTTP headers.

If you don't have a PAT yet, please request one by contacting us.

You can get your Shop ID by logging into your dashboard and copying it from the URL. Your Shop ID is the text string immediately after /dashboard/. For example:

https://dashboard.brikl.com/dashboard/63d6af47-5d4d-41cb-92f0-2455f4c3dc6f/home

In the URL above the Shop ID is 63d6af47-5d4d-41cb-92f0-2455f4c3dc6f. However, the Shop ID is not always a long text. Sometimes it's simply the name of your store. Just copy whatever it is, and you'll be good to go.

Setting up the Playground

With a Personal Access Token (PAT) and your Shop ID, you can start setting up the GraphQL Playground to make API calls.

1. Open the playground: https://api.brikl.com/graphql/admin/public.
2. In the bottom left corner, click on HTTP HEADERS.
3. Copy and paste the code below into the HTTP HEADERS pane:
   

{
  "Authorization": "PAT <token>",
  "X-Brikl-Shop-Id": "<shop-id>"
}

  4. Substitute <token> for you Personal Access Token (PAT), and <shop-id> for your Shop ID. Do not remove the quotes—they are necessary.

You're ready to go! Copy and paste the code below in the main left panel and click the play button:

query {
  schemaVersion
}

If everything works well, the query above will display the API schema version on the playground's right side:

{
  "data": {
    "schemaVersion": "v11-09-2021"
  }
}

Done! Your GraphQL Playground is working, and you can start making API calls to retrieve data from your Brikl store.

Accessing the sidebar docs

On the right side of the playground, you can access the collapsible Docs pane. The Docs pane allows you to browser documentation about the Brikl GraphQL API type system. The docs are automatically updated and will drop deprecated fields.

To read detailed and comprehensive descriptions of each field in the API, please refer to the Admin API reference.

Using the variables pane

Some API calls require variables, like the $order_id in the example below:

query($order_id: String!) {
  orderById(id: $order_id) {
    total
  }
}

To set the needed variables for an API call, use the QUERY VARIABLES pane on the bottom left corner of the playground:

{
  "order_id": "bdd1a06e-6293-423d-9023-62b58c6e0b7a"
}

Troubleshooting errors

Due to its introspection, the GraphQL Playground offers two interesting features:

1. Autocomplete. As you type, suggestions based on the current schema are provided.
2. Validation. Your query is analyzed in real-time as you type, and errors are warned.

If you type a query that is not well-formed or does not pass schema validation, the GraphQL Playground warns you of an error. If you go ahead and run the query, you'll get the error in the response pane.

A GraphQL error response usually contains an error array with details about the error:

{
  "error": {
    "errors": [
      {
        "message": "Variable \"$order_id\" of required type \"String!\" was not provided.",
        "locations": [
          {
            "line": 1,
            "column": 8
          }
        ],
        "extensions": {
          "code": "BAD_USER_INPUT"
        }
      }
    ]
  }
}

What's next?

Now that your GraphQL Playground is set up, you might want to learn how to create more real-world, sophisticated API calls to retrieve data from your Brikl store—so reach out to Forming calls with GraphQL.