There are two reasons why our first release uses GraphQL as the "One API for all Your Data."

GraphQL is better for a frontend developer

A couple of months into StepZen’s journey, we realized two things:

  1. Frontend developers are beginning to adopt GraphQL as the way to get data from backends, which is the raison d’etre for StepZen. The 2019 State of JavaScript survey for example reports that almost 40% of respondents have "used GraphQL, and would use it again", up from 20% in the 2018 survey; 50% of respondents have "heard of it, and would like to learn it."

  2. The cognitive overload in understanding the schema and query structures in GraphQL is low--and there is enough open source tooling that helps along the way. There are no Open API to read: open up your favorite tool (such as GraphQL Playground, or GraphiQL), and you have live documentation! In traditional REST calls--what you call and what you get back are only vaguely related: you have to parse the returned JSON and extract the bits yoy are interested in; whereas in GraphQL, what you get back is what you asked for (the shape of the response is the shape of the query). This is an awesome reduction in the cognitive overload on the frontend developer.

GraphQL is better for a backend developer

There are technical reasons too as to why GraphQL is simply better as a universal API. This makes the job of the backend developer easier.

Why REST as "One API for all your Data" leaves a lot of holes and GraphQL fixes most of these.

A REST API that would be "One API for all Your Data" would look something like this:

/oneAPI?q="select x where y"

As an example, x could be orders.productTitle and y could be customers.email=johndoe@example.com. But that immediately begs the question: what values of x are allowed, and what values of y are allowed, and what combination of these values are allowed? In relational databases, all queries are executable, some fast, some slowly. But in a world where the backends are what the backends are, this is no longer true. To show this, consider a query where

y:products.Id=2
x:customers.email

This is a perfectly valid request: let us say that a product with id=2 is recalled, and we might want to send mail to all customers who have bought the product.

However, typical backends are able to give data on what products a particular customer has bought, not which customers bought a particular product. Consequently, the above query might be very inefficient to execute (look through all orders of all customers and return those customers who had that particular product), or might not be executable at all.

So now, the backend developer must ensure that the frontend developer does not ask bad queries, and also, there are enough IDE integrations so that invalid queries are disallowed. So more work, more autogenerated code, longer and longer names of functions as helpers: getProductDetailsByCustomerId etc. All the stuff of nightmares.

This is much easier to solve in GraphQL. If the schema said:

type Customer {
    email: String
    …
    products: [Product]
}

and there is nothing in the schema like

type Product {
    id: Int
    …
    customers: [Customer]
}

Then the first query is executable, and the second query, simply by being absent in the schema, is not!

GraphQL makes stitching easier

If a backend developer wants to stitch multiple pieces of data together (say customer details with all his orders), and return them in one call, she has two choices:

  • Default to returning the stitched data (which would be wasted work if the frontend developer did not want that data), or
  • She adds artificial parameters like return=customer,orders which introduce cruft and cognitive overload.

Instead, in GraphQL, introspection will tell the frontend developer whether she can query stitched data together (so, no cruft of artifical parameters), and would also let the developer ask or not ask for stitched data.

That is why, in our current release, and all near-term releases, we only expose GraphQL as the interface--GraphQL is better for the frontend developer, and GraphQL is better for exposing backends. It is the right choice for "One API for all Your Data."