Vai al contenuto
Verificata

Chiamare un metodo

POST o GET, corpo o query string e cosa si aspetta il validatore dei campi.

Il nome di un metodo fa parte dell'URL. Ogni altro input, compreso un id, è un parametro: un campo del corpo JSON con POST, un parametro della query string con GET. Entrambe le forme raggiungono lo stesso metodo e restituiscono lo stesso formato di risposta.

POST: un corpo JSON

La forma normale per qualsiasi cosa con più di un paio di parametri, o con un oggetto annidato o un 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: una query string

Comoda per un controllo rapido dalla barra degli indirizzi del browser o con una riga di curl. Il server analizza la query string nello stesso corpo che vede il gestore del metodo, quindi le regole qui sotto contano più qui che con POST.

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

Il tipo dichiarato di un campo decide come viene letto il valore della query string:

  • string: usato così com'è.
  • number: passato attraverso Number(...).
  • boolean: solo la stringa letterale true viene letta come true. Qualsiasi altro valore passi per un campo booleano con GET, compreso false, viene convertito in un 1 truthy. Se un booleano è importante, invialo con POST con un vero true/false JSON, oppure ometti semplicemente il parametro della query per lasciarlo al valore predefinito del metodo.
  • object / array: il valore passa attraverso JSON.parse(...), quindi un valore annidato con GET deve essere un unico parametro della query che contiene una stringa JSON (filters=%7B%22status%22%3A%22open%22%7D), non un annidamento della query in stile parentesi.

Campi obbligatori ed errori di tipo

I campi di un metodo hanno ciascuno un flag mandatory e un type. Se manca un campo obbligatorio, o se invii il tipo sbagliato con POST (dove nulla viene convertito in automatico), ricevi un -1 prima ancora che il metodo stesso venga eseguito:

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

Il riferimento API interattivo elenca i campi di ogni metodo con i loro tipi e i flag di obbligatorietà, e ti permette di eseguire una chiamata dal browser per vedere la richiesta esatta che ha costruito.

Passi successivi