Usar IDs de nó globais

Você pode acessar a maioria dos objetos do GitHub (usuários, problemas, pull requests, etc.) usando a API REST ou a API do GraphQL. Você pode encontrar o ID de nó global de muitos objetos diretamente na API REST e usar esses IDs nas operações do GraphQL. Para ver mais informações, confira Pré-visualização de IDs de nó da API GraphQL nos recursos da API REST.

Colocando IDs de nó global em prática

Você pode seguir três etapas para usar efetivamente os IDs dos nós globais:

1. Chame um endpoint REST que retorna um node_id do objeto
2. Encontre o tipo do objeto no GraphQL.
3. Use o ID e o tipo para fazer uma consulta direta de nó no GraphQL.

Vamos analisar um exemplo.

1. Chamar um endpoint REST que retorna o ID do nó de um objeto

Se você solicitar autenticação do usuário:

curl -i --header "Authorization: Bearer YOUR-TOKEN" http(s)://HOSTNAME/api/v3/user

Você receberá uma resposta que contém a node_id do usuário autenticado:

{
  "login": "octocat",
  "id": 1,
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "gravatar_id": "",
  "url": "https://api.github.com/users/octocat",
  "html_url": "https://github.com/octocat",
  "followers_url": "https://api.github.com/users/octocat/followers",
  "following_url": "https://api.github.com/users/octocat/following{/other_user}",
  "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
  "organizations_url": "https://api.github.com/users/octocat/orgs",
  "repos_url": "https://api.github.com/users/octocat/repos",
  "events_url": "https://api.github.com/users/octocat/events{/privacy}",
  "received_events_url": "https://api.github.com/users/octocat/received_events",
  "type": "User",
  "site_admin": false,
  "name": "monalisa octocat",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "[email protected]",
  "hireable": false,
  "bio": "There once was...",
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "created_at": "2008-01-14T04:33:35Z",
  "updated_at": "2008-01-14T04:33:35Z",
  "private_gists": 81,
  "total_private_repos": 100,
  "owned_private_repos": 100,
  "disk_usage": 10000,
  "collaborators": 8,
  "two_factor_authentication": true,
  "plan": {
    "name": "Medium",
    "space": 400,
    "private_repos": 20,
    "collaborators": 0
  },
  "node_id": "MDQ6VXNlcjU4MzIzMQ=="
}

2. Encontrar o tipo do objeto no GraphQL

Neste exemplo, o valor de node_idé MDQ6VXNlcjU4MzIzMQ==. Você pode usar esse valor para consultar o mesmo objeto no GraphQL.

No entanto, você precisará saber o tipo do objeto primeiro. Você pode verificar o tipo com uma simples consulta do GraphQL:

query {
  node(id:"MDQ6VXNlcjU4MzIzMQ==") {
     __typename
  }
}

Esse tipo de consulta (ou seja, encontrar o nó pelo ID) é conhecido como uma "busca por nó direta".

Ao executar essa consulta, você verá que o __typename é User.

3. Fazer consulta direta de nó no GraphQL

Depois de confirmar o tipo, use um fragmento em linha para acessar o objeto pela ID e retornar dados adicionais. Neste exemplo, definimos os campos em User que desejamos consultar:

query {
  node(id:"MDQ6VXNlcjU4MzIzMQ==") {
   ... on User {
      name
      login
    }
  }
}

Este tipo de consulta é a abordagem-padrão para consultar um objeto pelo seu ID de nó global.

Usando os IDs de nós globais em migrações

Ao construir integrações que usam a API REST ou a API do GraphQL, considera-se uma prática recomendada persistir no ID de nó global para que você possa facilmente fazer referência a objetos entre nas versões da API. Para saber mais sobre como lidar com a transição entre a REST e o GraphQL, confira Fazer a migração de REST para o GraphQL.