Salesforce GraphQL API

13/11/2022

During the last few years, REST APIs have been the most relevant way to communicate between systems, as Salesforce relies on its necessity to integrate with other multiple systems. However, the CRM introduced the GraphQL API with the Summer ’22 release, a fresh and effective approach to search your organization’s sObjects for particular data and develop apps.

What is GraphQL?

As a server-side runtime for running queries utilizing a type system to create for your data, GraphQl is a query language for your API. Additionally, it is supported by your current code and data rather than being bound to any particular database or storage engine.

Apps that utilize GraphQL are significantly more effective and performant than those that use REST APIs since it provides a single endpoint to call for all the data required in a single request.

The advantage of GraphQL is that clients may make a single request for all the data they want, and unlike REST APIs, the answer will only contain the data they require.

Another handy benefit is that you can get back more than one object in a single standard request call, therefore reducing the impact on governor limits due to the fact that you obtain the data from a single request, instead of several calls – one of each object.

How to use GraphQL with Salesforce

During the last Salesforce release, Summer 22’, the GraphQL API was launched into the Beta phase. In this article, we will be covering three different possibilities to run your GraphQL requests: GraphSQL, GraphiQL, and Postman.

GraphSQL

The AppExchange store offers GraphSQL as a managed package extension for Salesforce, which is accessible for free. It enables you to submit GraphQL queries to the Salesforce API, making use of many of the amazing features that GraphQL has to offer and enhancing the performance and cost-effectiveness of your integrations.

This application is useful for testing out GraphQL queries since besides providing the JSON response you would normally expect, it also returns a list of the queries or mutations that were run to get the data, making debugging and understanding much easier. As of now, the features that are supported in GraphSQL are queries, arguments, aliases, variables, and mutations.

GraphiQL

The GraphiQL Foundation developed and maintains GraphiQL, an integrated development environment (IDE) for GraphQL. It is useful for running queries against a GraphQL server and exploring its schema documentation. Unlike GraphSQL, which comes in a managed package, you may use GraphiQL online, download a desktop version (exclusively for macOS and Linux as of now), or run it and host it yourself. To learn more on how to sync GraphiQL and Salesforce, check out “Exploring the Salesforce GraphQL API – Part Two”, in the References section.

Postman

In order to use the API, you need to make a POST request to the {{urlBase}}/services/data/{{version}}/graphql endpoint. Salesforce Developers provide a comprehensive collection of example requests in their Postman collection, available for consulting in the References section.

What’s relevant about GraphQL?

One of the key aspects is that due to the fact that GraphQL apps may receive all the data they require in a single invocation, they are able to eliminate round trips to the server and are thus far more performant than apps that utilize the REST API.

The response will only contain the data they needed, the data they requested – which is a huge plus since REST APIs usually returned more data than asked for. This lack of control over the information you receive is essentially unwanted data, which means wasted space, memory, resources, and avoidable costs overall.

To summarize this section, as Ben Sklar wrote in his entry on the Salesforce Developer’s Blog: “Unlike traditional REST APIs, with GraphQL, the power is in the hands of you, the developer. As a client, you can ask the server for exactly what you want and not receive any data you don’t need. You can avoid multiple round trips to the server since you can include in your request what traditionally would require calling multiple REST endpoints.”

Schema conventions

One of the most important parts of GraphQL is the Schema. The endpoint in GraphQL is connected to a schema made up of types and fields, where there exist several of those fields that conceptually resemble a REST API. Another relevant matter is Field selection, which is the process of indicating the fields we are interested in and only receiving that data back.

API families

Due to the schema being read-only for now, the only API family currently participating in the schema is UI API, which can be accessed via the uiapi field of type UIAPI. Each API family has a top-level field on the Query type, which serves as the entry point to that API family. The Query type has a uiapi field and a rateLimit field.

{ 
 type Query   
  uiapi: UIAPI,   
  rateLimit: RateLimit 
}

To make everything more understandable, developers may create user interfaces that allow users to interact with records, list views, actions, favorites, and more, by using the UI API. Furthermore, Lightning Experience, Salesforce for Android, iOS, and mobile web are all powered by this API. For more information, you may check the UI API developer guide linked in the References section.

{   
 uiapi {    
  # query resources from UI API here 
 } 
}

Pagination

A GraphQL server frequently uses pagination to organize types when dealing with a result set that has to be iterated over. It is particularly helpful when dealing with a lot of results. To iterate through the answer, use the first and after arguments.

Query Errors

If an error occurs while accessing a field, an error is added to the Errors list of the response. It contains a path that can be used to associate the error with the originally requested fields.

Versioning

GraphQL embeds a version of the API used for the duration of the request. All new types and fields added to Salesforce have an associated version, and the API version dictates the capabilities of the application when processing a request.

Get object metadata

By using objectInfo you will be able to return metadata from your choice of object. The response you receive includes metadata describing fields, child relationships, record type, and theme. You may use objectInfo by passing it in the uiapi field. For more information, make sure to check out the post in the Salesforce developers’ documentation, where it is well and thoroughly explained, in the References section.

{    
 uiapi { 
  objectInfo(apiNames: ["Account"]) { 
   # fields 
  } 
 } 
}

Further understanding of GraphQL – Request and Response Structure

We can divide a GraphQL request body into three different parts. The field named query contains the GraphQL query document as a string.

{ 
 "query": "query accounts {       
  uiapi {           
   query {               
    Contact {                   
     edges {                       
      node {                           
       Id                           
        FirstName {                               
       value                           
      }                       
     }                   
    }               
   }           
  }       
 } 
}

Under the operationName field, there is the query to execute, however, if the query document contains several queries or mutations, this field must be given in order to designate which query or mutation should be executed.

} 
 "operationName": "accounts" 
}

Last but not least, add any variables defined by the query as a map under the variables field.

"variables": { 
 "id": "001l2k394kwms92j17" 
}

The response contains two sections – data, where the query is contained, and errors, where any errors occurred during the execution of the request are included.

{ 
 "data": {...}, 
 "errors": [...] 
}

REST API or GraphQL?

We are all used to utilizing REST APIs whenever we want to build applications within Salesforce. Nevertheless, Salesforce bets on GraphQL as a new way of making your building experiences more reliable, precise, and efficient – a very important topic about the CRM is the support for different types of APIS (for instance, sObject API and UI API). Some of the benefits of using GraphQL with Salesforce that Ben Sklar states in his Salesforce Developers article are Field Selection, Resource Aggregation, Schema introspection, and sObject queryability. Without any doubt, they will come in handy whenever we want to interact with external systems from Salesforce.

If you’ve read until here, you might be wondering – why do we need a POST request if you said earlier the schema is in read-only mode? Well, in GraphQL, you provide a JSON-encoded body whether you’re performing a query or mutation, so the HTTP is nearly always POST. There’s an exception, though – Introspection queries (querying a GraphQL schema for details about itself) are always a simple GET to the endpoint.

{ 
 type __Schema  
 types: [__Type]  
 queryType: __Type  
 mutationType: __Type  
 directives: [__Directive] 
}

The future of app development in Salesforce

It is indeed tough to predict the future, and even more when it is regarding something constantly changing and evolving like the Salesforce development world. Just take a look at Lightning Web Components, Flows, DevOps Center, Code Builder, and many more – new additions that change the shape of how we develop our features and understand the Salesforce ecosystem.

Rest assured, the REST API won’t go deprecated any time soon, since it is still a great way of integrating with other systems, which many developers still feel confident with. In spite of that, it is relatively easy to learn how GraphQL functions, and if you’re already an experienced developer, catching up with this new feature will be quite simple. It is really a matter of 15 minutes to start sending requests with this amazing API.

Summary

GraphQL is an extremely interesting and well-documented topic, and it would be nearly impossible to cover all of it within a short article, such as this one. This new addition to Salesforce is for sure one of the most interesting ones the CRM has launched yet, and I’m pretty sure it has a long run and potential of becoming one of the most used ways of integrating between systems in the Salesforce ecosystem. Not only for its flexibility and efficiency but for the capability of being a great option for us developers when having to decide the best and optimal development approach.