3 ms·
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 communic
by yen223 8y ago
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.
- sgrove 8y agoThis 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 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 And so on and so on!