Uma Graph API é uma REST API, porém, seguindo uma modelagem de dados entre nodes e edges, permitindo executar a chamada de várias entidades de forma encadeada, com um único request. Apesar de ser um pouco diferente, isso não significa que todas as especificações anotadas na OpenAPI devam ser ignoradas, pelo contrário, segue fielmente as especificações de cada verbo http, por exemplo.
Não é raro a confusão entre o conceito de uma GraphAPI com o uso de GraphQL, esta segunda sim, é bem diferente do convencional, e só disponibiliza um único acesso GET e outro POST, recebendo uma consulta na semântica da graphQL.
Na composição de uma Graph API temos:
- nodes — basicamente objetos individuais, como um Usuário, Página Conta ou Comentário
- edges — conexões entre uma coleção de objetos com outros objetos
- fields — dados sobre um objeto.
Object ID’s
Os nodes, por representarem objetos individuais, obrigatoriamente possuem, cada um, a referência para um ID único no sistema inteiro. Assim sendo, para obter informações de um objeto, basta consultar diretamente pelo seu ID. Não precisa especificar o seu tipo na chamada.
1
GET 'HOST/{node-id}'
Fields
Para obter outros dados do objeto além do ID, é necessário especificar explicitamente na consulta, pelo parâmetro chamado fields.
1
GET 'HOST/{node-id}?fields={var1},{var2}'
Edges
Os relacionamentos entre objetos são encontrados pelas edges. Por padrão, elas retornam apenas ID’s, mas assim como é para os nodes, o parâmetro fields pode ser utilizado para retornar propriedades específicas em cada nível.
1
GET 'HOST/{node-id}/{edge}?fields={var1},{var2}...'
Exemplo → Facebook
Para exemplificar, apresento abaixo alguns exemplos de consultas reais do Facebook, que implementa em suas chamadas REST o conceito de Graph API.
Obter as contas de anúncio do usuário corrente, com nome da conta e o limite de gastos.
1
GET 'https://graph.facebook.com/v11.0/me/adaccounts?fields=id,name,spend_cap'
“me” é o node, “adaccounts” é a edge , e “id,name,spend_cap” são os fields.
Para cada conta de anúncio, é possível executar outra chamada para encontrar alguns dados das campanhas que estão dentro das contas de anúncio.
1
GET '.../v11.0/{adaccount-id}/campaigns?fields=id,name,objective,effective_status'
“{adaccount-id}” é o node, “campaigns” é a edge, e “id,name,objective,effective_status” são os fields.
No exemplo acima, se o usuário possuir 30 contas de anúncio, a chamada para buscar as campanhas deve ser invocada 30x.
Por isso, uma Graph API possui o grande trunfo: a busca encadeada.
1
GET '.../v11.0/me/adaccounts?fields=id,name,spend_cap,campaigns{id,name,objective,effective_status}'
Se você pensou “parece mágica”, bem-vindo ao clube!
Esta mesma explosão ocorreu-me em 2013, quando comecei a trabalhar com as Graph API’s do Facebook