GitHub spec versioning is ambiguous/overlapping

[pimterry]

There's quite a few different GitHub specs now since the update in #1069, and as far as I can tell, they're covering slightly different versions of the same API, but none has x-preferred set.

The current list is:

api.github.com.2022-11-28.json
api.github.com.json
ghec.2022-11-28.json
ghec.json
ghes-2.18.json
ghes-2.19.json
ghes-2.20.json
ghes-2.21.json
ghes-2.22.json
ghes-3.0.json
ghes-3.1.json
ghes-3.2.json
ghes-3.3.json
ghes-3.4.json
ghes-3.5.json
ghes-3.6.json
ghes-3.7.json
ghes-3.8.json
github.ae.json

It looks like GitHub AE & GHES are self-hosted & managed enterprise instances (GHES is GitHub Enterprise Server, and AE appears to be an extra-secure hosted version of that for governments etc) while the other 4 are all specs for the different versions of the API on same api.github.com URL.

2022-11-28 is the name of the latest (and currently only) version of the public API, I would guess that api.github.com.json is intended to be the official latest latest spec (and so I expect that may eventually diverge, but it's almost byte-for-byte identical to 2022-11-28 right now) while GHEC is GitHub Enterprise Cloud, which seems to be the same API at the same endpoint, but with a couple of extra endpoints only usable by enterprise customers, and with every documentation link linking to the separate enterprise-only site.

I think it'd be clearer if:

• GHEC & public APIs were considered as all being different versions of a single api.github.com API (with api.github.com.json the preferred version, since I think that's what 99.9% of people will be looking for)
• All GHES/AE versions are considered as different versions of the same GHES API, with the latest GHES version being the preferred option.

Is that possible?

[MikeRalphson]

GitHub API source URLs are of the form:

https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

We use a GitHub "driver" (that is, for any APIs extracted from a GitHub repo/archive, not just for GitHub themselves) to find and update the API definitions.

It takes a config of the form:

  driver: github
  glob: descriptions/**/*.json
  host: https://github.com/
  org: github
  branch: main
  repo: rest-api-description

enabling the detected serviceName to be split on a certain string or regex would enable all the GHES APIs to be considered the same service (and the x-preferred logic should kick in and tag the most recently added API).

We just need to be careful we don't split api.github.com and github.ae on the full-stop if we tried to put them all under one service (and we would have to tag x-preferred manually).

Leave it with me, and thanks for raising the issue.