Developer

GraphQL Playground

The GraphQL Playground provides a frontend UI for using Bluescape GraphQL API calls. You can access the playground via the 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 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: Notice that the GraphQL endpoint for your specific Bluescape instance will be displayed in the playground's address bar:

  • Box 2: You'll place your GraphQL API Request in the left-hand section of the playground:

  • Box 3: Clicking the QUERY VARIABLES tab will allow you to input your query parameters in the input field beneath it.

  • Box 4: Clicking the HTTP HEADERS tab will allow you 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. Please note that if your query, mutation or subscription has syntax errors, you will not be able to run it, the Play button will not be active.

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

  • Box 7: You can open a new query tab by clicking the + icon. This will allow you to write separate queries in new tabs.

  • Box 8: You can prettify your JSON query if you click the Prettify button.

  • Box 9: To see a history of the requests you've ran in the playground, click on this History tab. An example of what gets displayed when expanding this tab is shown below:


  • Box 10: To adjust the playground's settings, click on the Gear icon. This will open 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: You can copy the GraphQL API request as a cURL request by clicking the COPY CURL button. This will allow you to run the API request as a cURL request from the command-line.

  • Box 12: Opening the Docs tab will open 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: Opening the Schema tab will open 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 will allow you to download the schema, to 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'll go over an example Bluescape GraphQL API request using the GraphQL Playground. In this example, we will be retrieving 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.

    If you have any questions or comments, please contact us at Bluescape support.