Phase 12: GraphQL API for modern queries

[rianjs]

Overview

Add GraphQL API support for modern, flexible queries and mutations. The GraphQL API provides efficient data retrieval with field-level control and is fully GA as of Spring '26.

Parent issue: #17

12.1 GraphQL Client

Item	Title	Description
12.1.1	GraphQL client	api/graphql/ package
12.1.2	Query execution	Execute GraphQL queries
12.1.3	Mutations	Create/update/delete via GraphQL
12.1.4	Introspection	Schema discovery

Files:

• api/graphql/client.go
• api/graphql/types.go
• api/graphql/*_test.go

Key Types:

type GraphQLRequest struct {
    Query     string                 `json:"query"`
    Variables map[string]interface{} `json:"variables,omitempty"`
}

type GraphQLResponse struct {
    Data   json.RawMessage `json:"data"`
    Errors []GraphQLError  `json:"errors,omitempty"`
}

type GraphQLError struct {
    Message   string   `json:"message"`
    Locations []struct {
        Line   int `json:"line"`
        Column int `json:"column"`
    } `json:"locations,omitempty"`
    Path []interface{} `json:"path,omitempty"`
}

12.2 GraphQL Commands (sfdc graphql)

Item	Command	Description
12.2.1	sfdc graphql query	Execute GraphQL query
12.2.2	sfdc graphql mutate	Execute GraphQL mutation
12.2.3	sfdc graphql schema	Show schema info

Query Command

# Inline query
sfdc graphql query '{ uiapi { query { Account { edges { node { Id Name { value } } } } } } }'

# From file
sfdc graphql query --file query.graphql

# With variables
sfdc graphql query --file query.graphql --var "id=001xx000003DGbYAAW"

# Output as JSON (default)
sfdc graphql query '...' -o json

Mutation Command

# Create record
sfdc graphql mutate '
mutation {
  uiapi {
    AccountCreate(input: { Account: { Name: "New Account" } }) {
      Record { Id Name { value } }
    }
  }
}'

# From file
sfdc graphql mutate --file mutation.graphql

# With variables
sfdc graphql mutate --file mutation.graphql --var "name=Acme Corp"

Schema Command

# Get schema for object
sfdc graphql schema --type Account

# List available types
sfdc graphql schema --list

# Full introspection
sfdc graphql schema --introspect

Files:

• internal/cmd/graphqlcmd/graphql.go
• internal/cmd/graphqlcmd/query.go
• internal/cmd/graphqlcmd/mutate.go
• internal/cmd/graphqlcmd/schema.go
• internal/cmd/graphqlcmd/*_test.go

API Endpoint

POST /services/data/v62.0/graphql
Content-Type: application/json

{
  "query": "...",
  "variables": {...}
}

Example Queries

Query Records

query {
  uiapi {
    query {
      Account(first: 10) {
        edges {
          node {
            Id
            Name { value }
            Industry { value }
            Phone { value }
          }
        }
      }
    }
  }
}

Query with Filter

query {
  uiapi {
    query {
      Account(where: { Industry: { eq: "Technology" } }, first: 5) {
        edges {
          node {
            Id
            Name { value }
          }
        }
      }
    }
  }
}

Create Record (Mutation)

mutation {
  uiapi {
    AccountCreate(input: {
      Account: {
        Name: "New Account"
        Industry: "Technology"
      }
    }) {
      Record {
        Id
        Name { value }
      }
    }
  }
}

Update Record (Mutation)

mutation {
  uiapi {
    AccountUpdate(input: {
      Id: "001xx000003DGbYAAW"
      Account: {
        Phone: "555-1234"
      }
    }) {
      Record {
        Id
        Phone { value }
      }
    }
  }
}

Verification

# Simple query
sfdc graphql query '{ uiapi { query { Account(first: 3) { edges { node { Id Name { value } } } } } } }'

# Query from file
echo '{ uiapi { query { Account(first: 3) { edges { node { Id Name { value } } } } } } }' > test.graphql
sfdc graphql query --file test.graphql

# Schema introspection
sfdc graphql schema --type Account

Notes

• GraphQL API uses the uiapi namespace for UI API queries
• Field values are wrapped in { value } for nullable fields
• Pagination uses first, after, last, before arguments
• Filtering uses where with comparison operators
• Mutations follow the pattern {Object}Create, {Object}Update, {Object}Delete