Will the v3 REST API be updated over time?

Im looking to download all of the data for a repo, and have my code still work in the future.

Which API should I use?

  • v3 - JSON REST
  • v4 - GraphQL

Questions:

  1. Will new features data endpoints be added to the v3 JSON API over time to keep up with the GQL data?
  2. What is the difference between the two? Is all the GQL data available over REST?
  3. Will my code still work in around 5 years, or is there a plan to deprecate the v3 API?

I feel the v3 API is better for my use case (downloading all data), as I do not need to selectively download only part of the data set.

Advice appreciated.

Hi, hi, @broccolihighkicks :wave:

You pose some very interesting questions, most of which, don’t have an actually interesting answer, unfortunately. Though, if I did have those answers, one might wonder if I actually posses a functional crystal ball… =)

So, for:

Which API should I use?

This is not easy to say. As I write this, there is not feature parity between REST and GraphQL for GitHub. Each offer unique functionality not present in the other and without going into details of your use case, would be hard pressed to suggest one over the other.

If you have an immediate need, and you are more comfortable with REST, then there’s no real reason I would suggest GraphQL over REST.

If you are looking to expand beyond REST, and learn something new, I would definitely recommend using GraphQL. It’s far more flexible, and powerful, than REST alone.

But then we get back to that whole parity thing. It is true that each offering, has some endpoints/functionality, that the other doesn’t.


Onto the next Q:

Will new features data endpoints be added to the v3 JSON API over time to keep up with the GQL data?

Yes! Our v3 REST API will continue to be iterated on over time. In fact, there is far more that you can do right now with REST, that you cannot do with GraphQL.


And the next:

What is the difference between the two? Is all the GQL data available over REST?

As I’ve mentioned already, there is not 1:1 feature parity between the two, but it is a goal! I think for the “what are the differences,” we have this document:

…which I think provides helpful context to that question.

Please let us know if there’s anything remaining, there.


Finally:

Will my code still work in around 5 years, or is there a plan to deprecate the v3 API?

Ah, back to that crystal ball… :wink:

As far as I’m aware, there are no official plans to deprecate our REST API. This is of course, subject to change, and I highly recommend you follow our (rather new!) public roadmap:

…for updates. Something so substantial as deprecating our REST API would definitely be a big deal, and something we would overly communicate on.


I truly hope my response is helpful, but I know there’s some hypotheticals and some unknowns that you’re hoping to have solidified. Unfortunately, it’s really difficult to speak about that kind of thing in a public space =(

So please let us know if you had any more specific questions about either REST or GraphQL that we could field :bow:

Thanks for the reply. This makes it tough to choose.

So just to confirm, new fields are randomly added to either (REST, GQL) or both?

If I wanted to most complete and comprehensive view of the data, which API should I bet on?

I was considering GQL because in the GQL introduction post you mention the web UI is powered by GQL, so going forward it seems that would be the most complete?

One more question.

The REST API is optimised for polling (via the ETAG; no API quota is used when there are no events).

Is there an equivalent polling or subscription ability in GQL?

Happy to help, though…

This makes it tough to choose.

…is real! There’s truly not one explicit choice I can recommend.

Though for:

new fields are randomly added to either (REST, GQL) or both?

It is likely useful information to know that the maintenance and development of both REST and GraphQL spans across multiple teams. Since we also have tooling which uses our own APIs, we have to be very mindful about how and when we extend these resources.

So yes, each API offering is unique in its development cycle, but perhaps less “random,” than I may have alluded to.


Re:

going forward it seems that would be the most complete?

I probably sound a bit repetitive now but, I honestly can’t give an opinion on the completeness or the forward-looking assumption about moving towards GraphQL and away from REST.

Right now, REST is the most complete, but GraphQL is far more extensible, by its design. The goal of feature parity between the two, are very real.


Is there an equivalent polling or subscription ability in GQL?

In general, not all REST endpoints offer the same ETag option as the /events endpoint, does. So in GraphQL, we need to even be able to say that the same data is or is not available in GraphQL, which is also a complicated answer.

In fact, we have this thread:

…which discusses very relevant information, and is (for the most part) still accurate.

So whether there is a polling/subscription capability with GraphQL broadly, is less the question and more, does GraphQL do, what you want to do, that REST can do?

Relating to the /events endpoint? The answer is, kind of.


There truly is no one clear answer as to choose between REST or GraphQL and I would encourage you to think about your specific use case, and even consider using both!

My use case is: “Download all of the data for a given repo to a local database and keep it in sync”.

I cannot use webhooks as the client process is not a server.

I have tested polling GraphQL API, but neither the query cursor or the etag/if-none-match headers prevent my API quota being used (but in v3 polling does not use quota when there is no new data).

Question A: So, I do not think GraphQL will allow me to poll once per second without using all my quota on empty responses?