GitHub associates a unique resource ID (or "database ID" or just "ID") with each
API-accessible resource. For example, each issue,
repository, and user has a global ID. In my limited
experience with it, GitHub's REST API generally does not expose endpoints by
which resources can be queried by ID (though it does have some undocumented
endpoints). These resource IDs have been superseded by distinct
global node IDs (node_id
). GitHub's GraphQL API allows retrieval
of a node by its ID, called a "direct node lookup".
As you can tell, you likely don't have much reason to interact with the older identifiers directly. I encountered this case when using the ZenHub API, which interfaces with repositories only by resource ID. In my case, I wanted to retrieve a list of recently-closed issues from a set of repositories identified only by their resource ID (and without their owner or name).
This would be possible using the undocumented repository information REST endpoint I mentioned above, but I wanted to use the GraphQL API due to the amount of repositories I was interested in. GitHub's GraphQL API does not expose a means of querying repositories (or any object, to my understanding) by these resource IDs, so we need to manually convert them.
It turns out that the global node IDs are base64 encodings of a human-readable format. Take, for example, DataBiosphere/azul:
query {
azul: repository(owner:"DataBiosphere", name:"azul") {
id
databaseId
}
}
{
"data": {
"azul": {
"id": "MDEwOlJlcG9zaXRvcnkxMzkwOTU1Mzc=",
"databaseId": 139095537
}
}
}
If we decode the global node ID, we can see the pattern:
$ echo "MDEwOlJlcG9zaXRvcnkxMzkwOTU1Mzc=" | base64 --decode
010:Repository139095537
which we can infer is roughly equivalent to
{type_id}:{type_name}{resource_id}
. I'm pretty new to GraphQL, so I may have
butchered some of the terminology.
In any case, we can reverse this operation to calculate a global node ID from some resource identified only by resource ID:
$ echo -n "010:Repository139095537" | base64
MDEwOlJlcG9zaXRvcnkxMzkwOTU1Mzc=
query {
node(id:"MDEwOlJlcG9zaXRvcnkxMzkwOTU1MzcK") {
... on Repository {
nameWithOwner
}
}
}
{
"data": {
"node": {
"nameWithOwner": "DataBiosphere/azul"
}
}
}
Interestingly, this will work even with the trailing newline (i.e., calling
echo
in the above example without the -n
flag).
Hey @kastner.
Super helpful and gives me a massive head start. Thanks. I wish they gave a bit more documentation on their process, GH suggest they will provide tools to help convert from new to old etc, but I am sceptical to rely on their word here!
Thanks again. I wish there was more of a reputation system on GH, so I could
kudos
you for your help here! Hope I can return the favour with some help sometime in the future as it seems we have somewhat mutual interests.