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

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions