Exploring GraphQL API in Salesforce

GraphQL is a query language for fetching required data using API. It allows clients to request precisely the data they need from the server, making it more efficient and flexible compared to traditional REST APIs. It was developed by Facebook in 2012 and later open-sourced in 2015. GraphQL provides a more efficient, powerful, and flexible alternative to traditional RESTful APIs. This post will explain GraphQL API, its benefits and will also test this API using a GraphQL client.

GraphQL is a language for querying data from a number of different sources. It is not like SQL which queries data from one particular type of data source.

Types of Operations in GraphQL

Clients can perform mainly three types of operations: queries, mutations, and subscriptions. Each type has a distinct purpose and enables clients to interact with the GraphQL API in different ways.

1. Query

A query is used to fetch data from the GraphQL API. This is equivalent to REST’s GET calls. Clients can specify the exact data they need and its structure using a query language syntax. The query is submitted to the server, which processes it and provides the desired data in the exact form that the client requested. Queries are run synchronously, which means that the server processes the request and immediately sends the response.

In below code example, all records are returned from the account object. Only the Id and Name fields will return as specified in the API call.

2. Mutation

A mutation is used to change or add data to the server, similar to REST’s POST, PUT or DELETE methods. Salesforce is not supporting mutation right now.

In the below example, a new user creation request is sent and the server returns generated user-id after user creation.

3. Subscription

A subscription is used to get real-time server updates. Clients can subscribe to certain events and receive data when those events occur on the server. Subscriptions are frequently used to create features such as real-time messaging, live notifications, or any scenario in which clients must be notified of changes as they occur. This is also not supported yet in Salesforce.

The following is an example of client code required to subscribe to the addedPost mutation

Benefits of using GraphQL

GraphQL provides a number of advantages to developers, customers, and API providers, making it a popular choice for modern online and mobile apps. Here are some of the main benefits of utilising GraphQL:

Efficient Data Retrieval:

GraphQL allows clients to request only the information they require. This addresses frequent REST API over-fetching and under-fetching difficulties, resulting in more efficient data retrieval and lower network traffic.

Single Request, Multiple Resources

Clients can use GraphQL to request data from numerous resources in a single query. This minimises the number of round trips between the client and server, resulting in improved speed and lower latency.

Flexible Data Queries

Clients are free to tailor their data queries to their individual requirements. They can request nested data, related items, and even numerous searches in a single request, giving them more flexibility and reducing the need for additional API calls.

Strong Typing and Validation

GraphQL schemas are strongly typed, which means that the types and fields are explicitly stated. This aids in the detection of problems early in the development process and improves validation and auto-completion assistance in IDEs.

Security and Performance

GraphQL enables fine-grained control over data access because clients can only request fields and data that they are authorised to view. This can improve security and lower the chance of data leakage.

GraphQL API testing using Postman and Altair GraphQL Client

GraphQL API is generally available in Winter23. It can be consumed in Apex and LWC for retrieving different objects’ data. Let us see how we can test GraphQL using Postman and Altair GraphQL Client.

Steps for testing GraphQL

Create a Salesforce Connected App
Create a Salesforce User
Setup Postman to generate authentication Token
Use Altair GraphQL client to excute GraphQL query

Get an Authentication Token for GraphQL API

As mentioned above GraphQL API is secure and retrieves data based on user access. We need one Salesforce User and Connected App to test GraphQL API. Refer to our post Generate Salesforce Authentication Token using Postman to generate authentication token using Postman. Steps 1-3 are covered in this mentioned post.

Salesforce Authentication Token from Postman

We will need generated instance_url and access_token in below step.

Use Altair GraphQL client to excute GraphQL query

We need to download and install the Altair GraphQL client from its website. Once installation is complete we can use it for GraphQL API testing. This client needed an authentication token to execute the GraphQL query.

Set the authentication token, generated from Postman from the above step, to Altair GraphQL client headers.

Authentication Header - GraphQL API Client

This will set a access_token in the header and will be sent to the server on every request for secure access of API.

Now we can run GraphQL query in this client. Currently, we can only use the POST method for query execution.

URL : instance URL generated from Postman + /services/data/v57.0/graphql

Query:

You can use below query or your own query to test the GraphQL API.

Based on the above query, it will return account records.

References:

GraphQL API (Generally Available)

What is GraphQL API?