Skip to main content
A API GraphQL expõe um subconjunto suportado dos recursos REST do Ayrshare por meio de um único endpoint. Cada campo exposto chama o mesmo controlador subjacente que sua contraparte REST, então autenticação, permissões, cotas e dados de resposta seguem o comportamento do REST. O REST continua sendo a API mais ampla; use o schema ou o Explorer para ver exatamente quais operações o GraphQL suporta. O que ele acrescenta é a possibilidade de pedir várias coisas em uma única requisição e de descobrir a superfície GraphQL atualmente suportada a partir do próprio schema, sem ler a documentação página por página. O schema descreve cada campo de requisição suportado e as seleções tipadas disponíveis em respostas estruturadas; operações que retornam o envelope REST como JSON preservam esse payload completo.
Envie um POST com um corpo JSON contendo uma query, exatamente como em qualquer endpoint GraphQL. GET e DELETE retornam 405 Method Not Allowed — consultas via GET são opcionais na especificação GraphQL e não são suportadas aqui.

​
Sua primeira consulta

A resposta é o mesmo envelope JSON que o endpoint REST de histórico retorna, encapsulado no campo data do GraphQL:

​
Pedindo várias coisas de uma vez

O motivo para recorrer ao GraphQL é uma requisição como esta, que seriam quatro chamadas REST:
Uma única ida e volta retorna as quatro. Observe que são quatro campos de operação raiz e quatro chamadas de API para fins de cobrança, e não uma. Selecionar campos aninhados da resposta não adiciona chamadas — veja Limites e cobrança.

​
Autenticação

Idêntica ao REST. Envie sua API Key como um bearer token:
Se sua conta usa User Profiles, as operações que expõem profileKey podem selecionar um perfil de duas formas:
  • Envie Profile-Key como padrão para toda a requisição.
  • Passe profileKey em um campo individual para sobrescrever esse padrão, permitindo que uma única requisição atue em mais de um perfil.
O argumento do campo prevalece quando ambos estão presentes. Campos no nível da conta ou exclusivos da conta principal não expõem profileKey e podem rejeitar um cabeçalho Profile-Key; por exemplo, createProfile deve usar a API Key principal sem esse cabeçalho. Verifique a definição de schema de cada campo para saber seu escopo e veja Gerenciando vários usuários para entender como as Profile Keys funcionam.

​
Experimente sem escrever código

O GraphQL Explorer é um navegador interativo do schema atual. Ele lista todas as operações GraphQL disponíveis com seus argumentos e descrições, oferece autocompletar enquanto você digita e executa consultas na sua conta. Você não precisa de uma API Key para navegar pelo schema — o schema é público, assim como esta documentação. Você precisa de uma para executar uma consulta, porque toda operação passa pela mesma autenticação do REST.

​
Você deve usar GraphQL ou REST?

O REST continua sendo a interface principal e aquela em torno da qual a maior parte da nossa documentação, dos SDKs e das integrações foi construída. Recorra ao GraphQL quando:
  • Você precisa de várias informações não relacionadas e quer obtê-las em uma única ida e volta.
  • Você quer nomes de operações, argumentos, objetos de entrada, enums e seleções de resposta tipadas legíveis por máquina. A maioria das respostas continua sendo JSON para preservar o envelope REST completo; createPost atualmente retorna um PostResult tipado.
  • Você está explorando a API e quer ver o que existe sem navegar entre páginas da documentação.
Continue com o REST quando:
  • Você está enviando arquivos. Os bytes de mídia não podem trafegar por uma requisição GraphQL — veja Upload de mídia para o caminho suportado.
  • Você está usando um de nossos SDKs ou integrações no-code, que usam REST.
  • Você quer o menor número possível de dependências. Uma chamada REST não precisa de nada além de um cliente HTTP.
As duas interfaces são suportadas lado a lado, e você pode combiná-las livremente na mesma integração.
  • Usando a API — como encontrar operações, tipos de argumentos e upload de mídia.
  • Erros — quais falhas alteram o status HTTP, por que operações com falha ainda retornam HTTP 200 e como lidar com sucesso parcial.
  • Limites e cobrança — limites de tamanho de consulta e como as requisições são contabilizadas.