Salesforce GraphQL API Reference

Overview

Salesforce GraphQL requests are sent to a single endpoint:

• POST /services/data/vXX.X/graphql

The request body includes query, optional operationName, and optional variables. Responses use the standard GraphQL shape with data and errors.

Consensus Best Practices

• Use one operation per request for simpler tracing and error handling.
• Pass runtime values through variables instead of string-concatenating query text.
• Keep response selections minimal to reduce payload size and improve latency.
• Prefer lightning/graphql for most LWC use cases.
• Treat GraphQL as a read/query API first; validate mutation support by API version before rollout.

Request Contract

Endpoint

• POST /services/data/vXX.X/graphql

Request Body Fields

• query (required): GraphQL document text.
• operationName (optional): operation selector if document has more than one operation.
• variables (optional): key/value map used by the query document.

Example Request

{
  "query": "query accountSearch($name: String!) { uiapi { query { Account(first: 10, where: { Name: { like: $name } }) { edges { node { Id Name { value } Industry { value } } } } } } }",
  "operationName": "accountSearch",
  "variables": {
    "name": "Acme%"
  }
}

Response Shape

• data: successful payload (can be partial if some fields fail).
• errors: array of GraphQL errors.

LWC Integration

Preferred Adapter: lightning/graphql

Use lightning/graphql for most new implementations. It supports optional fields and dynamic query construction (API-version dependent).

import { LightningElement, wire } from 'lwc';
import { gql, graphql } from 'lightning/graphql';

const ACCOUNT_QUERY = gql`
  query accountSearch($name: String!) {
    uiapi {
      query {
        Account(first: 10, where: { Name: { like: $name } }) {
          edges {
            node {
              Id
              Name { value }
            }
          }
        }
      }
    }
  }
`;

export default class AccountSearch extends LightningElement {
  searchTerm = 'Acme%';

  get variables() {
    return { name: this.searchTerm };
  }

  @wire(graphql, {
    query: ACCOUNT_QUERY,
    variables: '$variables'
  })
  result;
}

lightning/uiGraphQLApi Usage

Use lightning/uiGraphQLApi only when Mobile Offline compatibility is required. Salesforce recommends lightning/graphql for general use.

Design Notes

GraphQL vs REST/Composite

• Use GraphQL when clients need flexible field selection in one endpoint.
• Use REST/Composite when you need explicit endpoint-level operations, existing REST tooling, or APIs not exposed in your GraphQL schema.

Versioning

• Keep API version explicit in your endpoint path.
• Re-validate query and mutation behavior during each Salesforce seasonal upgrade.

Common Failure Modes

• Query shape changes when schema/object metadata changes between orgs.
• Over-fetching too many nested fields leads to unnecessary payload and slower UI.
• Hard-coded query strings with inline values cause brittle code and injection risk.
• Assuming mutation support without checking API-version capabilities causes runtime failures.

Related Patterns

• LWC API Reference - LWC module usage patterns
• LWC Patterns - Component architecture and state patterns
• SOQL Reference - Query patterns for non-GraphQL surfaces

Q&A

Q: What is the Salesforce GraphQL endpoint?

A: Use POST /services/data/vXX.X/graphql, where vXX.X is your target API version.

Q: What fields are required in a GraphQL request body?

A: query is required. operationName is needed when multiple operations exist in one document. variables should hold runtime parameters.

Q: How should I pass dynamic values safely?

A: Use GraphQL variables (variables map) and keep the query text static.

Q: Which LWC GraphQL adapter should I choose?

A: Use lightning/graphql by default. Use lightning/uiGraphQLApi only when Mobile Offline support is required.

Q: Does Salesforce GraphQL support mutations?

A: Salesforce documentation states mutation support is available from newer API versions; validate exact behavior against your org and release version before production rollout.

Sources Used

• GraphQL API Requests and Responses: https://developer.salesforce.com/docs/platform/graphql/guide/requests-and-responses.html
• GraphQL API Get Started: https://developer.salesforce.com/docs/platform/graphql/guide/get-started.html
• LWC lightning/graphql Module Reference: https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-graphql-module.html
• LWC GraphQL Wire Adapter (lightning/graphql): https://developer.salesforce.com/docs/platform/lwc/guide/reference-graphql-wire.html
• LWC lightning/uiGraphQLApi Reference: https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-graphql-api?-escaped-fragment-=.html