Stronger signposting to GraphQL for statically-typed language users.

[sleekweasel]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

Because of how I reached the REST API pages, I just spent several days struggling to make OpenAPI work with Kotlin, and evaluating the third-party libraries, unaware that GraphQL was available.

it seems worth making explicit the current issues with OpenAPI for statically typed languages, and suggesting GraphQL alongside the third-party libraries, since the libraries are just a means to use GitHub and their API is an implementation detail.

What part(s) of the article would you like to see updated?

The Open API description page seems like a good place to mention the current problems with using GitlHub's polymorphic OpenAPI description with statically typed languages, and suggesting the third-party libraries and/or GraphQL as alternatives.

The libraries page also seems like a good place to mention GraphQL in the 'Official GitHub Library' section.

Additional information

No response

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[subatoi]

@sleekweasel Thanks for raising an issue and a PR, and linking them. I'm sorry you didn't have the best experience, but the pages you've suggested changing are specifically about the OpenAPI description, and the libraries, respectively. For that reason we're not going to accept this contribution at this time. We're also working on ways in which we can improve travel between pages generally, and don't want to pre-empt that work.

In the meantime, if it's something you feel particularly strongly about, I'd encourage you to open a community discussion so we can better evaluate how many users this affects.

Thanks for your interest in the GitHub docs and sorry this isn't the answer you're looking for. Please always feel free to take a look at our issues labelled help wanted.