Proposal: metadata file for endpoints

[WillAbides]

Contributing to and maintaining this repo could be helped by a metadata file for all of the endpoints go-github supports. It would map to GitHub's OpenAPI descriptions. In this proposal I'll call it operations.yaml.

An operations.yaml entry might look like:

- operation_id: pulls/request-reviewers
  openapi:
    method: POST
    endpoint_url: '/repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers'
    documentation_url: 'https://docs.github.com/rest/pulls/review-requests#request-reviewers-for-a-pull-request'
    summary: Request reviewers for a pull request
  go_method: PullRequestsService.RequestReviewers

operations.yaml could be updated by a scheduled GitHub action that opens a PR when it finds a change.

Initially operations.yaml would be useful for update-urls. Instead of having to resolve every documentation url, it could use the value stored in operations.yaml. update-urls could be expanded to also update godoc with the summary field.

It would also be useful for finding new endpoints for go-github to support. Eventually we could write a generator that uses operations.yaml to generate the boilerplate to implement new endpoints.

Overrides

There are probably endpoints where we don't want to use the OpenAPI data or maybe some that aren't even in the OpenAPI description. For those cases we can create an override section:

- operation_id: pulls/request-reviewers
  openapi:
    method: POST
    endpoint_url: '/repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers'
    documentation_url: 'https://docs.github.com/rest/pulls/review-requests#request-reviewers-for-a-pull-request'
    summary: Request reviewers for a pull request
  override:
    documentation_url: https://some/other/url
  go_method: PullRequestsService.RequestReviewers

For an endpoint that doesn't exist in the OpenAPI description, we create an entry with no openapi section and all required fields set in override. Here's a fictional PUT endpoint for the same url as above.

- operation_id: pulls/update-request-reviewers # manually created
  override:
    method: PUT
    endpoint_url: '/repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers'
    documentation_url: 'https://docs.github.com/rest/pulls/review-requestss#update-reviewers-for-a-pull-request'
    summary: Update reviewers for a pull request
  go_method: PullRequestsService.UpdateRequestReviewers

Multiple OpenAPI Descriptions

So far I've been talking about "the" OpenAPI description, but there are several docs published:

• one for api.github.com
• one for api.github.com with a GitHub Enterprise subscription
• one for each version of GitHub Enterprise Server released since v2.18
• one for github.ae

We will need a way to reconcile these. Knowing how GitHub generates these, I doubt there will be any significant differences between versions for the same operation_id. However they will have different documentation URLs. We can reconcile which one to use by taking the first one where the operation_id exists in this order: api.github.com -> ghec -> ghes versions in descending order -> maybe github.ae if anybody ever asks for it.

[WillAbides]

I would like to work on a proof-of-concept PR for this. There is a risk that this looks like a good idea but it ends up adding more complexity than it returns in value.

[gmlewis]

Are YAML and JSON our only two options?

[gmlewis]

Hey, @WillAbides - I love this proposal... it looks like you might be automating me out of a (volunteer) job... or at the very least, giving me longer vacations from said job.
😂

Seriously though, I'm a big fan of automation, and this sounds very cool indeed.

[WillAbides]

Are YAML and JSON our only two options?

You mean for the metadata file? Probably not, but I would prefer yaml or json because they are well known formats that show up nice in most editors. I've been looking for an excuse to use cuelang, but I wouldn't want to add something new to the cognitive load of understanding go-github.

it looks like you might be automating me out of a (volunteer) job

Hopefully only the thankless parts of the job.

[gmlewis]

OK, cool. SGTM regarding YAML.

cuelang is pretty awesome - I'm using it at work, actually. Lots of fun. 😄