Actions

The GraphQL connector spans 3 packages:

• ballerina/graphql
• ballerina/graphql.dataloader
• ballerina/graphql.subgraph

Available clients:

Client	Purpose
Client	Sends GraphQL queries and mutations to a remote GraphQL endpoint and returns type-safe responses.

For event-driven integration, see the Trigger Reference.

---

Client

Sends GraphQL queries and mutations to a remote GraphQL endpoint and returns type-safe responses.

Configuration

Field	Type	Default	Description
auth	ClientAuthConfig?	()	Authentication configuration. Supports CredentialsConfig, BearerTokenConfig, JwtIssuerConfig, OAuth2ClientCredentialsGrantConfig, OAuth2PasswordGrantConfig, OAuth2RefreshTokenGrantConfig, or OAuth2JwtBearerGrantConfig.
timeout	decimal	60	Request timeout in seconds.
retryConfig	RetryConfig?	()	Retry configuration for failed requests.
circuitBreaker	CircuitBreakerConfig?	()	Circuit breaker configuration for fault tolerance.
cache	CacheConfig	{}	HTTP response cache configuration.
compression	Compression	COMPRESSION_AUTO	Compression setting for requests.
secureSocket	ClientSecureSocket?	()	SSL/TLS configuration for HTTPS endpoints.
proxy	ProxyConfig?	()	Proxy server configuration.
validation	boolean	true	Enable or disable client-side GraphQL document validation.
followRedirects	FollowRedirects?	()	HTTP redirect following configuration.
cookieConfig	CookieConfig?	()	Cookie management configuration.
responseLimits	ResponseLimitConfigs	{}	Response size limit configuration.
http1Settings	ClientHttp1Settings	{}	HTTP/1.1-specific client settings.
poolConfig	PoolConfiguration?	()	Connection pool configuration.
forwarded	string	"disable"	Forwarded header handling mode.

Initializing the client

import ballerina/graphql;

configurable string serviceUrl = ?;

graphql:Client graphqlClient = check new (serviceUrl);

Operations

Query and mutation execution

execute

Sends a GraphQL document (query or mutation) to the remote endpoint and returns the response. Supports variables, operation name selection, custom headers, and type-safe response binding.

Parameters:

Name	Type	Required	Description
document	string	Yes	The GraphQL query or mutation document string.
variables	map<anydata>?	No	A map of variable names to values for parameterized queries.
operationName	string?	No	The name of the operation to execute when the document contains multiple operations.
headers	map<string|string[]>?	No	Additional HTTP headers to include in the request.
targetType	typedesc<GenericResponseWithErrors|record {}|json>	No	The expected response type for type-safe binding.

Returns: targetType|ClientError

Sample code:

json response = check graphqlClient->execute(
    string `query { allLifts { id name status } }`
);

Sample response:

{
  "data": {
    "allLifts": [
      {"id": "astra-express", "name": "Astra Express", "status": "OPEN"},
      {"id": "jazz-cat", "name": "Jazz Cat", "status": "OPEN"},
      {"id": "jolly-roger", "name": "Jolly Roger", "status": "CLOSED"}
    ]
  }
}