The package for Salesforce that aimed to provide a convenient way to communicate with a GraphQL server via Apex.
What is supported:
- Building queries, mutations and subscriptions
- Building graphql nodes (fields). If you want to send requests yourself
- Passing arguments to the graphql nodes (fields)
- Passing variables to the graphql operations from request
- Passing directives to the graphql operations and nodes
- Using fragments for graphql requests. Inline fragments are supported as well.
- Sync and async graphql HTTP client for sending requests (with callback implementation for async calls)
- Handling responses in GraphQL format
What is NOT supported:
- Sending subscription requests (WebSocket protocol is not supported by Apex)
If you think there is something that is not implemented yet as for GraphQL client I'd appreciate if you open an issue/discussion in this repository.
GraphQL node statement:
continents {
name
countries {
name
capital
currency
}
}
Equivalent Apex code:
GraphQLField continents = new GraphQLField('continents')
.withField('name')
.withField(new GraphQLField(
'countries',
new List<String> { 'name', 'capital', 'currency' }
));
// Will print a well-formatted node just like on the example above
System.debug(continents.build(true));
GraphQL query statement:
query {
countries(filter: "Bel", count: 1) {
name
capital
currency
}
continents {
name
}
}
Equivalent Apex code:
GraphQLField countries = new GraphQLField(
'countries',
new List<String> { 'name', 'capital', 'currency' }
)
.withArgument('filter', 'Bel')
.withArgument('count', 1);
GraphQLField continents = new GraphQLField(
'continents',
new List<String> { 'name' }
);
GraphQLQuery query = new GraphQLQuery(
new List<GraphQLField> { countries, continents }
);
System.debug(query.build(true));
After you created a query or mutation you can send it to the GraphQL endpoint:
...
GraphQLRequest request = query.asRequest();
// Add custom header if needed
request.withHeader('Authorization', 'Bearer token');
// Provide a GraphQL endpoint to the client
GraphQLHttpClient client = new GraphQLHttpClient('https://gql-endpoint.com/graphql');
GraphQLResponse response = client.send(request);
// Check if there are any errors and data
System.debug(response.hasErrors());
System.debug(response.hasData());
List<GraphQLResponseError> errors = response.getErrors();
Map<String, Object> dataAsMap = response.getData();
// It's also possible to get data as any Apex class type
SomeWrapper dataAsWrapper = (SomeWrapper) response.getDataAs(SomeWrapper.class);
Alternatively, sometimes it's easier to just send a request as a plain string, so you can do:
String query = 'query { countries { name, capital, currency } }';
GraphQLRequest request = new GraphQLRequest(query);
// Provide a GraphQL endpoint to the client
GraphQLHttpClient client = new GraphQLHttpClient('https://gql-endpoint.com/graphql');
GraphQLResponse response = client.send(request);
...
All examples can be found here.
You can just install the package by the link on a sandbox or dev org.
If you prefer using salesforce CLI you can simply run:
sfdx force:package:install -p 04t5Y000001zNZLQA2 -w 10 -b 10 -u <username>
You can also install the package with the automated scripts: pkg-deploy.sh
and pkg-from-scratch.sh
. First is for deploying changes to the existing org:
./scripts/pkg-deploy.sh <username>
Second is for creating a new configured scratch org:
./scripts/pkg-from-scratch.sh <devhub_username> <scratch_username>
The documentation describes all Apex types and usage cases for them. Please see it here.
If you have any questions you can start a discussion. If you think something works not as expected you can create an issue. If you want to request a new feature you can create an issue with the appropriate template selected.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate.