Saltar para o conteúdo
Verificado

Chamar um método

POST ou GET, corpo versus query string, e o que o validador de campos espera.

O nome do método faz parte do URL. Todos os outros dados de entrada, incluindo um id, são parâmetros: um campo do corpo JSON em POST, um parâmetro da query string em GET. Ambas as formas chegam ao mesmo método e devolvem o mesmo envelope.

POST: um corpo JSON

A forma normal para tudo o que tenha mais do que um par de parâmetros, ou com um objeto aninhado ou um array.

curl -s https://xuda.ai/cpi/agent_domain_connect \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","domain":"example.com","subdomain":"app"}'
const res = await fetch('https://xuda.ai/cpi/agent_domain_connect', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    domain: 'example.com',
    subdomain: 'app',
  }),
});
const { code, data } = await res.json();
if (code > 0) console.log(data);
import requests

res = requests.post(
    'https://xuda.ai/cpi/agent_domain_connect',
    json={'api_key': 'YOUR_API_KEY', 'domain': 'example.com', 'subdomain': 'app'},
)
body = res.json()
if body['code'] > 0:
    print(body['data'])

GET: uma query string

Útil para uma verificação rápida na barra de endereço de um navegador ou numa linha de curl. O servidor converte a query string no mesmo corpo que o handler do método vê, pelo que as regras abaixo importam mais aqui do que em POST.

cURL
curl -s 'https://xuda.ai/cpi/agent_domain_connect?api_key=YOUR_API_KEY&domain=example.com&subdomain=app'

O tipo declarado de um campo decide como o valor da query string é lido:

  • string: usado tal como está.
  • number: passado por Number(...).
  • boolean: apenas a string literal true é lida como true. Qualquer outra coisa que passe para um campo booleano em GET, incluindo false, é convertida num 1 verdadeiro. Se um booleano for importante, envie-o em POST com um true/false JSON real, ou simplesmente omita o parâmetro da query para o deixar no valor predefinido do método.
  • object / array: o valor é passado por JSON.parse(...), pelo que um valor aninhado em GET tem de ser um parâmetro da query com uma string JSON (filters=%7B%22status%22%3A%22open%22%7D), não um aninhamento de query ao estilo de parênteses retos.

Campos obrigatórios e erros de tipo

Cada campo de um método tem um indicador mandatory e um type. Faltar um campo obrigatório, ou enviar o tipo errado em POST (onde nada é convertido automaticamente), devolve um -1 antes de o próprio método sequer correr:

json
{ "code": -1, "data": "Error: 'domain' is a mandatory field" }
json
{ "code": -1, "data": "Error: 'domain' is a wrong type" }

A referência da API interativa lista os campos de todos os métodos com os seus tipos e indicadores de obrigatoriedade, e permite executar uma chamada a partir do navegador para ver o pedido exato que construiu.

Seguinte