Documentation
Feedback
Guides
App Development

App Development
GraphQL in VTEX IO
Admin GraphQL IDE

Learn how to make GraphQL queries in the Admin and use the IDE features.

Admin GraphQL IDE is an Admin app that allows users to make GraphQL queries. It includes GraphiQL, an open-source interface for writing, validating, and testing queries.

Admin GraphQL IDE allows developers to test and validate GraphQL APIs by providing features, such as:

  • Autocomplete.
  • Syntax highlighting.
  • Real-time error reporting.
  • Documentation explorer.

Before you begin

Make sure you have the VTEX IO CLI installed. If not, follow the instructions in Installing VTEX IO CLI.

Installing Admin GraphQL IDE

Follow these steps to install and open Admin GraphQL IDE:

  1. In a terminal, use the VTEX IO CLI to log in to your VTEX account.

  2. Run vtex use {workspaceName} --production to use a production workspace or create a production workspace from scratch.

    Remember to replace the values between curly brackets according to your scenario. To run tests, consider using a development workspace.

  3. Install the GraphQL IDE app by running vtex install vtex.admin-graphql-ide@3.x in your terminal.

  4. In your browser, go to https://{workspace}--{account}.myvtex.com/admin.

  5. Under Store Settings > Storefront, click GraphQL IDE.

    {"base64":"  ","img":{"width":301,"height":277,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":8486,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/graphql-ide-navigation.png"}}

    On the right side of your screen, you will now see a dropdown menu with the list of GraphQL APIs installed in the logged VTEX account.

Using Admin GraphQL IDE

The Admin GraphQL IDE interface is divided into three main sections:

  • One on the top left for writing queries.
  • Another is on the right to check the results.
  • A third one is on the bottom left, named Query Variables, which is optional and hidden at the bottom of the screen.

{"base64":"  ","img":{"width":1920,"height":791,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":98008,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/graphql-ide-1.png"}}

The Query Variables section is recommended when the same query will be reused many times with different arguments. To use dynamic values, you must place a dollar sign ($) before the variable name and then define the values for each field as JSON in the Query Variables section.

Follow these steps to make a GraphQL query:

  1. In the Choose an app dropdown menu, select the app you want to query.
  2. In the top-left box, write your query.
  3. If you need to use variables, click Query Variables in the bottom-left corner and insert your variables in the box using JSON format.
  4. Click Execute Query ▶️ to send your query. The result will appear on the panel to the right.

{"base64":"  ","img":{"width":1024,"height":544,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":121350,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/graphql-ide-query.gif"}}

Documentation Explorer

Another section of Admin GraphQL IDE is the Documentation Explorer, which can be found in the upper right-hand corner of the IDE. The Documentation Explorer allows developers to better understand a particular query, mutation, or type structure by providing a description and information about its schema.

{"base64":"  ","img":{"width":348,"height":544,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":115230,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/graphql-ide-docs.gif"}}

History

Another feature of Admin GraphQL IDE is keeping a log of all the queries and mutations that are run, which can be viewed through the History dashboard. If you click one of the queries from the History list, the query code will appear in the top-left box.

{"base64":"  ","img":{"width":616,"height":201,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":20270,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/graphql-ide-history.gif"}}

Shortcuts

When writing a query in Admin GraphQL IDE, some useful shortcuts are:

  • Ctrl + Space (or Shift + Space) to display the autocomplete popup.
  • Ctrl + Enter to run the GraphQL query.
  • Ctrl + Shift + P to fix the indentation.
Contributors
1
Photo of the contributor
Was this helpful?
Yes
No
Suggest Edits (GitHub)
Contributors
1
Photo of the contributor
On this page