I recently wrote that I believe people choose GraphQL because of the way it addresses common frustrations with web APIs. I'd like to look at this from the perspective of GraphQL to see why they think people should like GraphQL by looking at their marketing site. Though they mention technical reasons throughout the page, they're clear about the pain points they try to resolve.
When are there moments of frustration?
There is a moment in time right before a person decides to look for a solution where a frustration or need drives them to action. Good marketing will take people to these moments, tell a compelling story, and offer relief. Basecamp is a company that does this well on their landing page.
All growing businesses run into the same fundamental problems. Hair on fire, buried under email, stuff everywhere. The good news? Basecamp solves them.
Instead of focusing on their product, Basecamp focuses on the frustrations people feel when dealing notifications coming from all directions at work. They want to help create a calmer work experience, and they do so by providing a project management tool. These moments of frustration tell us why they think people should like Basecamp.
The frustrations addressed by GraphQL
The GraphQL landing page also takes this approach, though it's not as explicit. If we dig into what they are saying, we'll find the frustrating moments they feel GraphQL addresses. We'll look at the main points on the GraphQL landing page and consider what a person might be feeling before choosing GraphQL.
"Why can't I have more control over the API?"
The site says, "Ask for what you need, get exactly that." Client developers may be taken back to times when they had to sift through payloads looking for the data they needed. Though GraphQL results in smaller initial responses, I'm not sure this is the driving factor for most. People know what data they need. Why should they deal with more? Why do they have to go through the extra work when they could use GraphQL and get what they ask for?
"I can't figure out how this data is related."
"Get many resources in a single request," they say. But we've had solutions for ages that do this. Why is GraphQL different? They give us a hint.
GraphQL queries access not just the properties of one resource but also smoothly follow references between them.
GraphQL tries to expose the interconnectedness of the data. For many web APIs, it's a difficult task to understand how all of resources are related, but with GraphQL, it's one of the primary ways you interact with and understand the data.
"It's difficult to write usable and helpful docs."
When they say, "Describe what’s possible with a type system," they are making a statement about what wasn't possible without types. You might have thought while reading API docs, "I read it all, and I still don't know what I can do with this API." The type system gives developers direction and becomes it's own documentation.
"My tools require me to do a lot."
They say, "Move faster with powerful developer tools." They want to have tools that promote speed and agility in development while being simple to use. Instead of jumping between docs and tools to piece together multiple requests, GraphiQL lets you navigate the docs and build requests in the same tool. Most people didn't realize how badly they wanted this until they saw it.
"It's hard to reliably make changes to my API."
It takes work to evolve an API. Most people reach for versioning as a way to manage API changes. It's one of the first discussions people have when starting a new API—"How are we going to version our API? In the URL? Headers? Are the versions global?" The GraphQL site addresses versioning in their best practices:
When there's limited control over the data that's returned from an API endpoint, any change can be considered a breaking change, and breaking changes require a new version.
In their landing page they say, "Evolve your API without versions." They want you to forget everything you know about versioning. Can you evolve REST APIs without versions? Sure. But it's still uncommon to see, so much so that it's a main point of their marketing.
A recipe for traditional web APIs
If you're building tooling for traditional web APIs, I feel you could focus on these same frustrations and address the same users who are switching to GraphQL. I'd love to see people create tools and practices to address these issues within the REST paradigm—bonus points for working with common API best practices.
There are many tradeoffs in the GraphQL vs. REST discussion that need to be worked through (read more here and here). Maybe we can find ways get the benefits of REST with the ease and simplicity of GraphQL.
Top comments (0)