graphql-api-patterns

# 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:

1. Gather context — confirm the org edition, relevant objects, and current configuration state
2. Review official sources — check the references in this skill's well-architected.md before making changes
3. Implement or advise — apply the patterns from Core Concepts and Common Patterns sections above
4. Validate — run the skill's checker script and verify against the Review Checklist below
5. 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 `uiGraphQLApi` is 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:

1. **GraphQL is easy to over-fetch** - one endpoint does not make huge nested payloads free.
2. **`lightning/uiGraphQLApi` is not the default choice** - use it when offline compatibility is required, not just because it exists.
3. **`data` and `errors` can coexist** - clients that only check one branch miss partial failures.
4. **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.