Utilize Octokit resources

[gr2m]

👋 Hello there, I’m the maintainer of the GitHub’s JavaScript/Node libraries such as https://github.com/octokit/rest.js.

In the process I created resources that I hope will make it easier for maintainers of libraries for GitHub’s platform such as go-github

For example

1. octokit/routes - machine-readable, always up-to-date GitHub REST API route specifications. I use it to generate all methods and update documentation / Typescript definitions.
2. octokit/webhooks – same as routes, but for webhooks
3. octokit/fixtures - scenario fixtures for integration testing. Updated nightly.

I wonder if any of these would be useful to you? I'd be happy to chat and learn more about the challenges you are facing and if there is anything we can do to make it easier to maintain go-github.

Thanks for creating and maintaining such a great library! I only hear great things from people using it 👏

[gmlewis]

Wow... those look absolutely fantastic, @gr2m!
Thank you very much for the pointers and the kind words!
@willnorris has done amazing work on this repo and I'm having fun helping out to maintain it.

I love automating things and am going to have to study your resources to see how we could possibly take advantage of them!

And if any of our wonderful contributors wants to check these resources out and share your ideas, feel free to add them to this issue and we can chat about them!

[gr2m]

Hey friends, just a heads up that the https://github.com/octokit/routes/ repo is now an OpenAPI spec, maybe that will make it easier to consume? I've also created a GraphQL Server which allows to query the endpoints from OpenAPI to make them easier to consume for SDKs: https://octokit-routes-graphql-server.now.sh. And I created an app which creates a repository_dispatch event for each new release of the spec: https://github.com/apps/octokit-routes

Here is the GitHub Action workflow from the JS SDK to update the SDK when the repository receives the dispatch: https://github.com/octokit/rest.js/blob/master/.github/workflows/update-rest-endpoint-methods.yml

Let me know if you have any questions :)

[willnorris]

This is great, thanks! (And someone I missed seeing your original post back in February!)

The last time I looked, the go libraries for OpenAPI were pretty lacking, which is rather disappointing. We'll definitely try taking a look at this though, and see if we can find a way to use this data to improve the go-github library.

/cc @gauntface @rspier as fyi

[willnorris]

oh wild... I also just realized that you're reverse engineering this from the API documentation. I really wish GitHub would officially publish something like this :-\

Though to be fair, I just added a screen scraping client to go-github, so I've got no problem with whatever approach gets the job done :)

[gr2m]

I didn't end up using the OpenAPI directly to generate my SDK and supportive libraries, I've found the format is not very easy to parse, even with extensive tooling in the JS ecosystem. That's why I created the GraphQL server as an abstraction, and I'm more than happy to collaborate to make it as easy to consume for go-github as possible.

I also just realized that you're reverse engineering this from the API documentation. I really wish GitHub would officially publish something like this :-\

Yeah :) There is a growing interest for OpenAPI within GitHub, so an official OpenAPI spec might come some day. Until then, the one from octokit/routes is fairly stable and complete, no need to wait for an officially published version