GraphQL Playground

The GraphQL Playground provides a frontend UI for using Bluescape GraphQL API calls. You can access the playground via the GraphQL Playground page.

To gain a better understanding of how Bluescape uses GraphQL, see the What is GraphQL? page.

Table of Contents:

How to Use the GraphQL Playground

In this section, we’ll start with a general explanation of how to use the GraphQL Playground. In the next section, API Example using the GraphQL Playground, we’ll go over a specific example.

You can access the playground via the GraphQL Playground page.

After accessing the link, you should see the main GraphQL Playground page:

For the remainder of this section, we’ll reference the image below, which has highlighted areas of importance in the playground:

  • Box 1: The GraphQL endpoint for your specific Bluescape instance is displayed in the playground’s address bar:

  • Box 2: Place your GraphQL API Request in the left-hand section of the playground:

  • Box 3: Click the QUERY VARIABLES tab to input your query parameters in the input field beneath it.

  • Box 4: Click the HTTP HEADERS tab to input your HTTP headers in the input field beneath it.

  • Box 5: To run your query, press the Play button in the middle of the playground. Note that if your query, mutation, or subscription has syntax errors, you are not able to run it, and the Play button will not be active.

  • Box 6: After running the query, your API response is displayed in this section.

  • Box 7: Click the + icon to open a new query tab. This allows you to write separate queries in new tabs.

  • Box 8: Click the Prettify button to prettify your JSON query.

  • Box 9: Click on the History tab to see a history of the requests you’ve run in the playground. An example of what gets displayed when expanding this tab is shown below:

  • Box 10: Click on the Gear icon to adjust the playground’s settings. This opens up a new Settings tab, as seen in the example below:

Be sure to click Save Settings in the top-right to see them reflected in the playground.

  • Box 11: Click the COPY CURL button to copy the GraphQL API request as a cURL request. This allows you to run the API request as a cURL request from the command line.

  • Box 12: Opening the Docs tab opens up the documentation for all of the GraphQL APIs that are available to you in the playground. See the example below, which displays the documentation for the id field of an Element:

  • Box 13: Selecting the Schema tab opens up the schema information for all of the GraphQL APIs available to you in the playground. See the example below:

Notice the Download button in the top right. This allows you to download the schema, so it can be used in other tools such as Postman, for autocompletion of the queries, mutations, and subscriptions.

API Example using the GraphQL Playground

In this section, we go over an example Bluescape GraphQL API request using the GraphQL Playground. In this example, we will retrieve a list of all the elements in a given workspace. We’ll also utilize a key feature of GraphQL: the ability to only retrieve specific fields from a given API request.

Specifically, we’ll retrieve only the type, id and (x,y) fields from the response of a call to the /workspace/{workspaceId}/elements endpoint.

We’ll reference the screenshot below for the remainder of this section:

  • Box A: First, we’ll place the example request in the API Request section of the playground.

  • Box B: Next, we’ll need to update the QUERY VARIABLES section with the necessary query headers for this API call. In this example, we need only the workspaceId parameter.
    For this section, you’ll also need to input an authorization token into the HTTP HEADERS section. You’ll need to click on HTTP HEADERS and provide the following:

  "authorization": "Bearer <SET_TOKEN>"
  • Box C: Press the Play button to run the request.

  • Box D: You can see the results of the request in this section. Notice that all of the elements in the workspace are returned showing only the parameters we specified: type, id, and (x,y).

Keep in mind that you can still utilize all of the other features of the GraphQL Playground in this example. You can inspect the documentation, schema, etc. if you wish.
To get more information about GraphQL at Bluescape, refer to the documentation found in our other Guides pages.

Where to Next?

Not what you were looking for? Reply below or Search the community and discover more Bluescape.