The Hidden Benefits of GraphQL: Making Data Accessible to Everyone

The Ice Cream Conundrum

Imagine you’re craving ice cream on a warm summer day. You want to know which flavor to choose, but there are so many options! You need to consider dietary restrictions, ingredient preferences, and nutritional values. How can we build a tool to help with this decision? Fortunately, our favorite ice cream brand has a public API that we can use to make informed choices.

The Problem with REST

When we query the API, we get a list of flavors with some information, but not everything we need. We have to make multiple calls to different endpoints to get the details about each flavor, ingredient, and allergen. This complexity makes it difficult for non-technical people to understand and use the API.

GET /flavors
GET /flavors/:id/ingredients
GET /flavors/:id/allergens

The GraphQL Advantage

GraphQL promotes the use of a single endpoint for the entire API, reducing the cognitive load for users. It’s a declarative language, which means we need to explicitly describe what information we want, solving the problems of under-fetching and over-fetching. With GraphQL, we can combine multiple requests into a single query, hiding the complexity of the system from the user.

query {
  flavors {
    id
    name
    ingredients {
      name
      quantity
    }
    allergens {
      name
      severity
    }
  }
}

A Guided Tour Through the Data

GraphQL’s self-documenting capabilities make it easy to navigate through the data structure, even for those without technical knowledge. Its strongly typed language provides auto-completing and suggesting fields as we type our queries, guiding us through the data.

Making Data Accessible

By using GraphQL, we can make data more accessible to everyone, regardless of technical background. We can build a service that is more approachable, relevant, and usable by all kinds of people.

Action Points for a More Human-Friendly API

• Use a single endpoint: Reduce cognitive load and enhance discoverability.
• Build the GraphQL schema with humans in mind: Rethink the way your data is connected to make it more understandable.
• Extend existing services, don’t replace them: Build on top of existing APIs to make it easier to start using GraphQL.
• Use GraphQL’s features and tools: Provide different ways to navigate through the data to empower users.

Want to see these principles in action? Check out figma-graphql.com, a human-first GraphQL service built on top of the Figma REST API. Share your thoughts and feedback with us on Twitter!