tomevault-io Graphql Api Patterns
Use this skill when the integration question is really about query shape and client efficiency, not just about calling another endpoint. Salesforce GraphQL is strongest when a consumer needs flexible field selection from a single endpoint and wants to avoid a chain of UI API or REST requests.
Before Starting
Gather this context before working on anything in this domain:
- Is the consumer an LWC, Experience Cloud page, mobile client, or server-side integration?
- Does the use case need flexible reads, aggregations, pagination, or mutation behavior that is supported in the target API version?
- Is mobile offline support required, or is standard online LWC behavior enough?
Core Concepts
GraphQL Is A Single Endpoint With Client-Shaped Responses
Salesforce GraphQL requests go to /services/data/vXX.X/graphql. The client controls the selection set, so payload size and nesting discipline matter more than they do with fixed REST resources.
Variables Beat String-Built Query Text
Keep the query document stable and pass runtime values through GraphQL variables. This improves safety, readability, and cache behavior. String-building query text with user input is the wrong default.
Adapter Choice Matters In LWC
For most new LWC use cases, prefer lightning/graphql. Use lightning/uiGraphQLApi only when Mobile Offline compatibility is the actual requirement. Treat adapter selection as an architectural decision, not just an import statement.
Partial Data And Pagination Need Intentional Handling
GraphQL can return data and errors together. Connection-style pagination and cursor handling should be part of the design, not an afterthought added once result sets get large.
Common Patterns
LWC Query Adapter Pattern
When to use: An LWC needs flexible reads with fewer round trips than separate wire adapters or Apex endpoints.
How it works: Define a static gql document, pass runtime values through variables, and keep the selection set intentionally small.
Why not the alternative: Raw fetch() calls to the endpoint duplicate logic the platform adapter already handles.
GraphQL For View Models, REST For Operational Actions
When to use: The UI needs shaped read data, but writes or side effects are clearer in REST or Apex services.
How it works: Use GraphQL to gather the read model and keep operational commands on dedicated APIs.
Cursor-Based Pagination
When to use: Result sets can exceed a single page and the client needs stable incremental loading.
How it works: Use the connection model and track cursors instead of assuming offset-style paging.
Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
| Client needs flexible read shape from one endpoint | GraphQL | Reduces over-fetching and request fan-out |
| Team needs explicit endpoint contracts for operational actions | REST or Apex REST | Better fit for command-style APIs |
| LWC needs GraphQL and offline support | lightning/uiGraphQLApi |
Adapter exists for that narrower requirement |
| LWC needs GraphQL without offline requirement | lightning/graphql |
Preferred default adapter for most new work |
Recommended Workflow
Step-by-step instructions for an AI agent or practitioner activating this skill:
- Gather context — confirm the org edition, relevant objects, and current configuration state
- Review official sources — check the references in this skill's well-architected.md before making changes
- Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
- Validate — run the skill's checker script and verify against the Review Checklist below
- Document — record any deviations from standard patterns and update the template if needed
Review Checklist
Run through these before marking work in this area complete:
- Query text is stable and runtime values move through variables.
- Selection sets are minimal and not over-fetching nested data.
- Adapter choice is justified, especially if
uiGraphQLApiis used. - Pagination and partial-error handling are part of the design.
- Mutation support is validated against the target API version before rollout.
- REST, Composite, and GraphQL are compared deliberately instead of by trend.
Salesforce-Specific Gotchas
Non-obvious platform behaviors that cause real production problems:
- GraphQL is easy to over-fetch - one endpoint does not make huge nested payloads free.
lightning/uiGraphQLApiis not the default choice - use it when offline compatibility is required, not just because it exists.dataanderrorscan coexist - clients that only check one branch miss partial failures.- Mutation assumptions drift by API version and surface - validate supported behavior before promising write patterns.
Output Artifacts
| Artifact | Description |
|---|---|
| API choice review | Recommendation for GraphQL versus REST or Composite |
| Query design review | Findings on variables, selection sets, pagination, and adapter use |
| GraphQL request scaffold | Stable query document and variables pattern for the chosen client |
Related Skills
lwc/lifecycle-hooks- use when the real problem is LWC state, rendering, or cleanup rather than the GraphQL contract.integration/oauth-flows-and-connected-apps- use when authentication and connected-app design are the real blockers around the API.apex/apex-rest-services- use when the org needs a custom command API rather than a client-shaped read surface.
Source: PranavNagrecha/AwesomeSalesforceSkills — distributed by TomeVault.