Calling an endpoint is only half the story. You still need to know the shape of the response. And most rest APIs I've had to use do a suboptimal job at communicating the schema of the response.
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.
This is a great point - Stripe is one of the exceptional companies that maintains a great openapi spec though!
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
}
}
}
}
}
}
- Type (and nullability!) of fields
- 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
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.