Ecosystem Community Update

GraphQL Considerations – Ecosystem Update

Hey all :wave:

Back again to share some general insights about GitHub’s GraphQL API limitations that may not be obvious from our documentation.

REST and GraphQL APIs each have a 10s global timeout

Did you know that our APIs have an enforced 10s timeout, which cannot be adjusted? We call this out in our REST troubleshooting document, here:

However, it might not be obvious to folks using GraphQL, when we return errors like:

Something went wrong while executing your query. This may be the result of a timeout, or it could be a GitHub bug.

Which can be incredibly misleading and frustrating, when your query might seem fine and doesn’t return an error 100% of the time. While the error message suggests it may be a result of a timeout, it very often is exactly a timeout.

So when we look at our documentation for GraphQL limits:

…we see that there is no mention of that global 10s timeout, that we saw in the REST documentation.

What can you do to avoid this?

Because of this 10s timeout, a user must be very careful to not submit overly complex queries. Though how will you know if your query is overly complex? That error message suggests what might have gone wrong, but it’s not explicit enough.

If you are calling for lists of Repositories, or Pull Requests, at a large count, our immediate suggestion would be to lower the count, and leverage GraphQL’s pagination process:

…which is unique to the standard REST method of returning a numbered list of pages.

Also consider the number of unique fields being requested. If you have many fields in a query that might already be requesting say, a large count of certain information from one source, any additional fields will all add up to the same 10s timeout for a single query.

So consider lowering the complexity of individual requests, as well as lowering the counts of requested data.

What the heck are we doing to address the experience?

A few things!

  • We have open issues to adjust the aforementioned error messaging
  • We plan to update our documentation to be more explicit
  • Performance enhancement plans for long-running fields

That’s it for now, but we’ll be back again soon!

Cheers, and we’ll see you at Universe!