Figuring out the syntax/language to do something as simple as retrieving the first X items requires more thought than calling a dead-simple REST endpoint.
Even Stripe's API, which is far ahead of most other APIs in terms of documentation, doesn't tell you basic things like whether a field can ever be null.
GraphQL defines an interface for describing the schema of an endpoint. This to me is the most valuable thing about it.
Even so, the GraphQL experience (with the explorer and some other OSS releases we have for next week) is still just so exciting https://serve.onegraph.com/short/Q8SE4F :D
query search {
stripe {
invoices(first: 10) {
nodes {
amountDue
nextPaymentAttempt
object
total
customer {
... on StripeCustomer {
id
email
}
}
charge {
dispute {
created
reason
status
}
}
}
}
}
}
- In-situ documentation on what the fields are for
- Ability to navigate the Stripe graph from any starting point (customer -> charges -> cards) in a single super-efficient call
- Search-ability across the whole Stripe API in a single field
- Potentially joins across services, e.g. from Stripe to Zendesk or Salesforce
And so on and so on!
I think the more interesting question is whether GraphQL is a suitable inter-application API foundation. In many ways it aligns better with application requirements than gRPC. gRPC is even farther away from REST, with limited abilities to do field selection and no inherent support for nesting. And gRPC needs special help to work in browsers. What gRPC has is a compact serialization format and a toolchain that encourages using Protobuf structs for your own internals.
When implementing an app, it certainly seems redundant to offer both GraphQL and gRPC.
Nothing about GraphQL prevents using e.g. protobufs in theory, but in practice 99.99+% expect to send/receive son.
For complex APIs that are used by consumers for many tasks, it can make sense though.
If you are using GraphQL internally, you might as well expose a version of it to customers.
See for example Github, which has a GraphQL API.
REST shortcomings aren't necessarily found in a single api request. REST's shortcomings are the handful of endpoints required to get the information you actually want.
That's a problem of a naive CRUD API against a normalized relational datastore (or one structurally resembling such a store) regardless of architectural style, but there is no reason any standardized packet of information for which there is an expected recurring need should not be conceptualized as a resource in a REST API.
Orthogonality or normalization is not part of the REST architectural style.
Even more, now I'm using postgrahile and don't even bother with writing the backend for much of anything except special case resolvers. This has increased my productive time but it might not be a fit for everyone. The nice thing is that I keep my schema in the app repo and have the entire thing provisioned from 1 script.
If I need a new resource I just modify the database schema and the graphql resolvers are created automatically.
I'm obviously biased as one of the founders of OneGraph. There's a one-time cost of learning the syntax (which we're trying to make easier!), but once you've done that my experience is that it's easier to use a GraphQL endpoint from the backend than a REST endpoint.
We used Facebook's GraphQL endpoint from a Clojure backend when I joined the Wit team after they were acquired. It was very handy to be able to look at the query and have a general idea of the data that was going to be returned rather than inspect a response or look up the docs.
I ran into one issue recently from a server side client use case where I needed to quickly consume an entire endpoint. Since you need to define each field in your query, it was more time consuming to create the requests. I also see the issue if fields are added, you would miss that data without updating your query.
Typically these are benefits when doing frontend work, to limit data, but I did find it annoying when just needing to quickly dump data.
For my own servers moving forward, I’m going to be adding a _doc json field for users that need traditional rest endpoint functionality in a query.
Its of course much better to define your attributes ahead-of-time. It incurs more overhead initially but pays off immensely down the line.
I use a hand-written generator which generates a "AllXXFields" fragment for each type automatically.
There are obviously tradeoffs that come with selecting all fields by default (in particular it makes it difficult for the server devs to send thoughtful notifications only to clients who rely on specific fields when necessary), but for initially exploring it's definitely nice.
It was surprising to us as well! But working with lots of users who are new to GraphQL, there are a few speed bumps along the way before you get to "implementing GraphQL in production." You have to convince your GraphQL users that:
1. It won't take too long to understand 2. It will be worth the effort
Anything you can do to make building a valid GraphQL query (both syntactically and semantically) faster helps with #1, and will get your users further along.
Making it so that users can see success/data flowing in as quickly as possible helps with #2.
From there, like you mentioned, there are lots of additional challenges, but for this post we're focusing on getting new users over the most initial hurdles.
Authorization, that is, allowing users access to some things but not others, is more complicated and of course bespoke to your application. The simple solution is to simply check context in individual resolvers, which ends up looking a lot like a normal Express/Flask/Sinatra app.
There is a graphql-middleware package that helps structure "middleware" resolvers, and a graphql-shield package that helps with more complicated role-based logic.
If possible it would be good to add default values too (like the "ticker" in the stock data set)!
The explorer supports adding args that should be auto-checked and providing default values. It could probably be a little easier to use, but it's easy enough to add new ones once you have an example: https://github.com/OneGraph/graphiql-explorer-example/blob/m...
Full Disclosure: I work at Hasura.
In my opinion, a well designed API should be as easy to explore as folders on a computer, and the GraphiQL Explorer makes this the case by default.
I like odata a lot more, but it's more initial work