This blog was updated in November 2022 as GraphQL API is now generally available. 

We are excited to announce that we’re investing further in our experience APIs with the launch of the Salesforce GraphQL API. As of Winter ’23, the Salesforce GraphQL API is generally available. This API allows developers to interact with the Salesforce Platform through GraphQL, providing a new way to create rich, performant mobile and web applications.

What’s wrong with traditional REST APIs?

Imagine you’re out at your favorite restaurant — in this case we’ll call it the RESTaurant. Your waiter comes over to your table and asks, “What would you like to order?” You reply, “I’ll take the ravioli, but please, no cheese.” To your chagrin, your waiter explains, “The cheese has already been added and can’t be removed. You’ll get the ravioli with the cheese, or you’ll have to order something else.” Herein lies a fundamental problem with traditional REST endpoints — you as the client can’t change what the Cheese Ravioli Endpoint returns back to you. Had this restaurant been the GraphQL Restaurant, you could order ravioli without cheese.

Okay, so I know what you might be thinking: “But, I thought REST was the gold standard for APIs?” You’re not wrong; REST is still a great way to design and implement APIs. However, traditional REST APIs have some challenges when it comes to building today’s highly performant and scalable web and mobile apps.

Let’s explore all of the flaws with traditional REST APIs, go over what GraphQL is, and how GraphQL solves these problems. We’ll also discuss other GraphQL benefits, such as the ability to query your organization’s data for specific information. Once you realize all the advantages of a GraphQL API, you’ll want to leverage it to build the best apps for your users.

What is GraphQL?

GraphQL is a standard query language for APIs and a runtime for fulfilling those queries with your data. A GraphQL API is a new paradigm of sending and receiving data, offering clients a single endpoint to call for all data needed in one request. Apps that call GraphQL APIs are often much more performant than those that use traditional REST APIs. This is because they are able to reduce round trips to the server through their ability to retrieve all necessary data in just a single invocation. Not only can clients query for all the data they want in a single request, but the response will contain only the data they need. Nothing more, nothing less. GraphQL is a new way to address many pain points for application developers; it is an open specification backed by a diverse community that has seen success at high scale.

Developers lack control with traditional REST APIs

Traditional REST APIs have some shortcomings. Let’s say you make a call to a traditional REST API, and your use case is looking up a user’s phone number. Most likely, you’ll make a call to a REST API endpoint that gives you all the data that you have permission to access about that user. So, rather than just retrieving a user’s phone number, you’ll also receive their address, their manager’s name, etc. In short, everything returned back to you that isn’t the user’s phone number is wasted data — which is an unnecessary cost to both the server and you. Sure, you could use query parameters on every REST endpoint to prevent this problem of overfetching data with REST APIs. The problem is that there aren’t widely adopted standards for this, so not every endpoint out there today has it, and it may compete with already limited space in the URL. If an endpoint doesn’t have this functionality, then there’s nothing you can do. With GraphQL, you include all the fields in your query that you’re interested in, and receive only the data for those fields — a feature known as “field selection.”

Too much data returned in a single API request may be wasteful. Why don’t we just create a multitude of endpoints that return very specific pieces of data to limit this waste? This results in far too many REST endpoints, which makes it even harder for developers to determine the right one they need to call. However, if you do want all associated data, you would have to call each one of these endpoints to get what you need, with each call resulting in another round trip to the server. As a developer of an application, you want good performance for your users. One way to achieve this is to minimize network trips and unnecessary data transfer between the client and server, since each additional round trip adds latency. This issue is especially pronounced for mobile users who may have limited connectivity or bandwidth. A GraphQL API solves this problem by allowing for resource aggregation, or in other words, the ability to retrieve all the data your app needs in just one request.

As discussed, it’s often the case that REST APIs have limited or no support for things like field selection and aggregation. Developers are frequently left with difficult tradeoffs that distract from building the best possible experience for their users. So, how do you build an app with incredible performance and no data waste? The solution is quite simple: a single REST endpoint whose response has exactly what you need — with nothing extra. The problem is that this endpoint doesn’t exist. Okay, so as a developer, you request that a new REST endpoint be created with all of your exact needs. However, you know that it’s unrealistic to think that a new endpoint will be created for every possible use case. But, wouldn’t it be great if you could control what fields and which resources the server returns to you? Well, now you’ll be able to with the new Salesforce GraphQL API: a single endpoint whose response can be shaped by you.

GraphQL puts the power into the hands of developers

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. Using powerful tools like GraphiQL, a web IDE for GraphQL, you can introspect the schema and quickly learn how to make a request for the data you need.

In mobile and web apps, time spent on the network is usually a significant part of the overall request processing time, with every round trip resulting in longer wait times. This can lead to user dissatisfaction, lower app usage, and worse conversion rates. With GraphQL, you no longer need to worry about dealing with multiple endpoints and going back and forth with the server to retrieve the data you need. As a developer, you are free to focus on your own software requirements without agonizing about how many endpoints you need to call, or how you’re going to stitch together all the data you receive. There’s no need to write multiple abstraction layers, nor do you need to spend your time orchestrating API call after API call.

What this means for Salesforce developers

Even though there are imperfections with traditional REST APIs when building experiences, they still do have a place, and we aren’t dropping our investment there. Rather, a key strength of the Salesforce Platform is our support for various type of APIs. System APIs, such as the sObject API, or experience APIs like UI API, have enabled developers to build a wide variety of applications using the Salesforce Platform. With the new Salesforce GraphQL API, we’re providing even more benefits for Salesforce developers, including:

• Field selection
• Resource aggregation
• Schema introspection
• sObject queryability

What’s Next

Although today we support querying (reads), we are working hard to bring mutations to the API as well (writes). We are also working on a GraphQL Wire Adapter that will bring native GraphQL support to Lightning Web Components (LWC). We are planning to bring these new features in the next year.

About the Authors

Spencer MacKinnon is a Developer at Salesforce who has spent too much time thinking about GraphQL. He used to have hobbies, but now spends his evenings chasing around his puppy, Merope. Follow him @smackinnon.

Ben Sklar is a Senior Product Manager at Salesforce who is a major fan of GraphQL. He is an avid skier, but spends most of his time playing with his Cavapoo, Percy.