GraphQL

Yasumu's GraphQL module is a full-featured GraphQL client built right into your workspace. It lets you write queries, explore schemas, build operations visually, and run requests — all without leaving Yasumu.

Getting Started

Setting up a GraphQL request takes just a few clicks:

Interface Overview

The GraphQL module is split into three main areas:

The request editor and response panel sit side by side in a resizable split view. You can switch between horizontal and vertical layouts using the layout toggle.

File Tree

The file tree on the left sidebar is where you organize all your GraphQL entities.

Creating Entities

• Click the + button to create a new request
• Right-click to create folders for grouping related operations
• Give entities descriptive names — they're stored inside the file, not as the file name

Organizing with Folders

Group related requests into folders by functionality. You can nest folders to any depth.

Context Menu Actions

Right-click any entity or folder to access:

• Rename — Change the display name
• Duplicate — Create a copy of the entity or entire folder
• Copy / Cut / Paste — Move entities between folders
• Delete — Remove the entity or folder

URL Bar & Introspection

The URL bar sits at the top of the request editor.

Entering a URL

Type or paste your GraphQL endpoint URL. The URL supports environment variables using the {{VARIABLE}} syntax:

{{API_URL}}/graphql

Variables are resolved from the currently active environment at request time.

Introspecting the Schema

Click the Introspect button (next to the URL bar) to fetch the schema from your endpoint. Introspection:

• Enables IntelliSense in the query editor (autocomplete, error highlighting)
• Populates the Query Builder with all available operations
• Fills the Documentation viewer with the full type system
• Unlocks the Entity Importer for bulk generation

Sending Requests

Click Send or press Ctrl+Enter (⌘+Enter on macOS) to execute the request. While a request is in progress, the button changes to Cancel so you can abort it if needed.

Query Editor

The Query tab is the heart of the GraphQL module. It contains three sub-views:

• Editor — A full-featured code editor for writing queries
• Query Builder — A visual, point-and-click query constructor
• Documentation — An interactive schema documentation browser

Switch between them using the sub-tab buttons at the top of the Query panel.

Editor

The editor uses Monaco (the same engine behind VS Code) with full GraphQL language support:

• Syntax highlighting for GraphQL queries
• IntelliSense autocomplete — field names, types, and arguments are suggested as you type (requires introspection)
• Error highlighting — invalid queries are underlined in real time
• Variable support — reference environment variables with {{VARIABLE}}

Write standard GraphQL queries, mutations, or subscriptions:

query GetUsers($limit: Int) {
  users(limit: $limit) {
    id
    name
    email
  }
}

Query Builder

The Query Builder lets you construct queries visually — no need to write GraphQL syntax by hand.

How It Works

Field Documentation on Hover

Hover over the info icon (ℹ) next to any field to see a documentation popup showing the field signature, description, parameters, and return type.

Filtering Fields

Use the search box in the toolbar to quickly filter fields by name. This is especially useful for schemas with many operations.

Schema Documentation

The Documentation sub-tab provides an interactive, searchable browser for your entire GraphQL schema.

Browsing Types

The left sidebar lists all types organized by category:

Type Detail View

Click any type to view its full documentation in the main panel:

• Type badge — Shows whether it's a Query, Mutation, Object, Enum, etc.
• Description — The type's description from the schema
• Fields — Each field with its name, arguments, return type, and description
• Clickable type links — Click on any type reference to navigate to its documentation

Searching Types

Use the search box at the top of the sidebar to filter types by name. This makes it easy to find specific types in large schemas.

Variables Editor

The Variables tab lets you define the variables for your GraphQL query.

Table Mode

The default view shows a table where you can manage variables visually:

Click Add Variable to add a new row, or the trash icon to remove one.

JSON Mode

Switch to JSON mode for direct editing of the variables object:

{
  "userId": "123",
  "limit": 10
}

Both modes stay in sync — changes in one are reflected in the other.

Parameters & Headers

Parameters Tab

The Params tab manages URL parameters for your request:

• Path Parameters — Automatically detected from :param syntax in your URL (e.g., https://api.example.com/:version/graphql)
• Search Parameters — Query string key-value pairs appended to the URL

Headers Tab

The Headers tab lets you add custom HTTP headers to the request. Common use cases include:

• Authorization — Bearer {{API_TOKEN}}
• Custom headers — Any header your API requires

Each header has a key, value, and enable/disable toggle. Headers support environment variables with {{VARIABLE}} syntax.

Scripting

The Scripts tab lets you write JavaScript code that runs at different stages of the request lifecycle:

• onRequest(req) — Runs before the request is sent. Modify headers, variables, or the URL.
• onResponse(req, res) — Runs after the response is received. Process response data or update environment variables.
• onTest(req, res) — Define test assertions against the response.

Example Script

// modify request
export function onRequest(req: YasumuRequest) {
  req.headers.set('Authorization', `Bearer ${req.env.getSecret('API_TOKEN')}`)
}

// consume response
export function onResponse(req: YasumuRequest, res: YasumuResponse) {
  const body = res.json<any>();
  console.log(body.data.products.items[0]);
}

// run tests
export function onTest(req: YasumuRequest, res: YasumuResponse) {
  test('Response status should be 200', () => {
    expect(res.status).toBe(200);
  });
}

The script editor includes TypeScript type definitions for autocomplete and error checking.

Entity Importer

The Entity Importer (also called the GraphQL Generator) can automatically generate request entities for every operation in your GraphQL schema. This is a huge time saver when working with a new API.

How to Use

Response Panel

After sending a request, the response panel displays the result.

Status Bar

The status bar at the top shows:

• Status Code — HTTP response status (color-coded: green for 2xx, yellow for 3xx, orange for 4xx, red for 5xx)
• Response Time — How long the request took
• Response Size — Size of the response payload
• Error Count — Number of GraphQL errors, if any

Response Tabs

The Errors and Console tabs appear only when there is content to display. If the response contains errors, Yasumu automatically focuses the Errors tab.

Tab Features

• Click a tab to switch between open entities
• Middle-click a tab to close it
• Hover over a tab to see the entity name and endpoint URL
• The active tab has a highlighted indicator at the bottom

Environment Selector

The environment selector sits at the end of the tab bar. Switch between environments to change which variables are used when resolving {{VARIABLE}} references.

Keyboard Shortcuts

Best Practices

1. Introspect early — Always introspect the schema first to unlock IntelliSense, the Query Builder, and Documentation
2. Use the Entity Importer — When working with a new API, use the importer to scaffold all operations in seconds
3. Organize with folders — Group related operations (e.g., by resource or domain) for easy navigation
4. Use environment variables — Avoid hardcoding URLs and tokens. Use {{VARIABLE}} syntax and switch environments as needed
5. Write scripts for auth — Use onRequest scripts to automatically attach authentication headers
6. Add tests — Use onTest to validate responses and catch regressions
7. Commit to version control — GraphQL entities are stored as .ysl files, designed for clean diffs and collaboration