Skip to content

Add GraphQL query cookbook (example queries by use case) #1199

@dkijania

Description

@dkijania

Part of #1195 (Track 2).

Goal

A cookbook of practical, copy-pasteable GraphQL queries split by use case. Each example its own .mdx page so it's individually searchable, indexable, and linkable.

Why split into per-use-case pages

A single prose page (today's docs/node-developers/graphql-api.mdx) buries useful examples in long-form text. A flat list of focused pages — each titled by what the user is trying to do — is easier for both humans (search) and agents (URL-pattern navigation).

This complements the schema-generated reference (sibling issue): reference tells you what each field is; cookbook tells you which fields to combine for common tasks.

Proposed contents

Each as its own .mdx under docs/integrate/graphql-api/cookbook/:

  • account-balance.mdx — Get an account's balance, nonce, delegate.
  • watch-new-blocks.mdx — Subscribe to newBlock, filter by producer.
  • estimate-fee.mdx — Use pooledUserCommands to estimate a sensible fee.
  • find-transaction.mdx — Look up a transaction in the archive node.
  • pending-transactions.mdx — Inspect the mempool.
  • block-by-height.mdx — Fetch a specific block via archive GraphQL.
  • delegation-info.mdx — Account staking and delegate chain.
  • network-status.mdx — Sync state, peers, current epoch / slot.
  • submit-payment.mdx — Mutation example (with --insecure-rest-server warning).

(Pick the ones that actually map to common questions; cut/add as needed.)

Page template

Each page should follow:

  1. What this does (one sentence).
  2. When to use it (one sentence — what real workflow needs this).
  3. Query (fenced graphql block).
  4. Variables (if any).
  5. Example response (truncated).
  6. Notes / gotchas (e.g. "memo is Base58Check encoded", "only last k blocks via daemon — use archive for older").
  7. Related: links to relevant schema-generated reference pages and other cookbook entries.

Acceptance criteria

  • Cookbook directory created with at least 6 starter recipes.
  • Each page follows the template above.
  • Sidebar entry under Integrate with Mina → GraphQL API → Cookbook.
  • Cross-links between related recipes.
  • Cross-links from each recipe to the relevant generated reference pages (depends on sibling issue).
  • llms-full.txt regenerated.

Depends on

Section structure from #1195 Track 1. If that lands first, slot under docs/integrate/. Otherwise temporary path under docs/node-developers/graphql-cookbook/ and move later.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions