WAPI – Manuale

In questo articolo scoprirà:

• Come funziona WAPI e a cosa serve
• Come attivare WAPI nell’amministrazione clienti
• Come avvengono la comunicazione e l’autenticazione
• Jak stránkovat a hledat v seznamech
• Comandi di base
• Elenco dei codici di ritorno
• Glossario

---

WEDOS API

WEDOS API, ovvero WAPI, serve a gestire i servizi direttamente dal Suo sistema informativo. 

Condizione per l’utilizzo dell’interfaccia è l’impiego di un conto prepagato WEDOS, dal quale il sistema detrae i pagamenti per registrazioni, rinnovi, trasferimenti e altri costi addebitati.

Attualmente WAPI consente la gestione di:

• Conto prepagato ⧉ (account-* e nelle credit-*)
• Domini ⧉ (domains-* e nelle domain-*)
• Contatti dei domini ⧉ (contact-*)
• NSSET ⧉ (nsset-*)
• DNS ⧉ (dns-*)
• Utenti autorizzati di WEDOS Global ⧉ (wg-members-*)
• WEDOS Protection ⧉ (wgp-services-* e nelle wgp-domain-*)

Limitazioni di WAPI

Come protezione contro gli abusi, WAPI applica le seguenti limitazioni:

• Con un solo account utente è possibile inviare al massimo 1000 richieste all’ora. Il limite riguarda tutte le richieste di ogni tipo; una volta raggiunto, WAPI rifiuta le richieste successive fino alla scadenza del limite di tempo.
• Un account utente può inviare al massimo 100 richieste di disponibilità di un dominio all’ora. Il limite riguarda i comandi domain-check, domain-create e domain-transfer-check.
• Invio ripetuto di richieste non valide (errore di autorizzazione, accesso da un indirizzo IP non consentito, input errato, parametri mancanti o non corretti, comando sconosciuto, comandi che terminano con un errore qualsiasi o qualsiasi richiesta che superi gli altri limiti) comporta, al superamento di 10 richieste non valide, il blocco dell’indirizzo IP per 1 minuto per ogni richiesta non valida. Con ogni ulteriore richiesta errata il sistema prolunga la durata del blocco.

Operazioni sincrone e asincrone

La maggior parte dei comandi eseguiti tramite WAPI è sincrona: invia il comando e di norma entro pochi secondi riceve il risultato. 

Alcune operazioni sono asincrone, quindi l’esecuzione di un comando di questo tipo può richiedere molto tempo (anche ore o giorni). WAPI non restituisce quindi il risultato finale, ma solo l’informazione che il comando è stato accettato. Le informazioni sull’avanzamento e il risultato finale Le vengono poi inviati dal sistema sotto forma di notifiche.

Registrazione (log)

Il log delle richieste si trova nell’amministrazione clienti seguendo questi passaggi:

1. Acceda all‘ amministrazione clienti ⧉.
2. Nel menu in alto selezioni My Account Customer.
3. Nel menu a sinistra selezioni WAPI queries.

---

Attivazione di WAPI nell’amministrazione clienti

Prima di iniziare a usare WAPI, lo attivi nell’amministrazione clienti seguendo questi passaggi:

1. Acceda all‘ amministrazione clienti ⧉.
2. Nel menu in alto selezioni My Account Customer.
3. Nel menu a sinistra selezioni WAPI interface.
4. Imposti gli indirizzi IP consentiti (IPv4 o IPv6, è supportato CIDR), la modalità di notifica, il protocollo preferito e la password.
5. Confermi le impostazioni con i pulsanti Set.

---

Comunicazione e autenticazione

La comunicazione con l’interfaccia WAPI avviene tramite il protocollo HTTPS. I dati vengono trasmessi con il metodo POST nel parametro request in formato XML o JSON. La forma di base del comando e della risposta è la stessa per tutti i comandi. La codifica dei dati è UTF-8.

Indirizzi URL dell’interfaccia:

• XML: https://api.wedos.com/wapi/xml
• JSON: https://api.wedos.com/wapi/json

Struttura della richiesta

La richiesta è composta dai seguenti dati:

• user: nome utente (e-mail) del Suo account cliente, parametro obbligatorio.
• auth: stringa di autorizzazione, parametro obbligatorio. Si tratta dell’hash sha1 di una stringa composta dal nome utente, dall’hash sha1 della password WAPI e dall’ora corrente (00-23). Il fuso orario è Europe/Prague (ora invernale UTC+1 CET, ora legale UTC+2 CEST). Per un esempio concreto veda il codice qui sotto.
• command: il comando WAPI vero e proprio. Parametro obbligatorio.
• clTRID: ID della richiesta, parametro facoltativo. In questo elemento può inserire una stringa qualsiasi come identificatore, che WAPI restituirà nella risposta.
• data: parte dati del comando. Parametro facoltativo.
• test: indicatore della modalità di test, parametro facoltativo. Se inserisce nel comando l’elemento test con valore 1, WAPI si limita a verificare il comando, ma non esegue alcuna modifica.

Il modello della richiesta (JSON) è quindi:

{
  "request":
  {
    "user": "suo@login.tld",
    "auth": "stringa di autorizzazione",
    "command": "nome della richiesta",
    "data":
    {
      dati della richiesta
    }
    "clTRID": "identificatore della richiesta (facoltativo)",
    "test": "1 (se desidera solo testare la richiesta, facoltativo)"
  }
}

Un esempio completo di utilizzo in PHP (formato dati JSON) può quindi essere:

<?php 
date_default_timezone_set('Europe/Prague'); 
$login = 'suo@login.tld'; 
$wpass = 'la sua password WAPI'; 
$auth = sha1($login.sha1($wpass).date('H', time())); 
$url = 'https://api.wedos.com/wapi/json'; 
$input = [ 'request' => [
  'user' => $login,
  'auth' => $auth,
  'command' => 'nome della richiesta',
  'data' => ['array dei dati della richiesta'],
  'clTRID' => 'identificatore della richiesta (facoltativo)',
  'test' => '1 (se desidera solo testare la richiesta)'
  ]
];

$post = json_encode($input);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_TIMEOUT,60);
curl_setopt($ch,CURLOPT_POST,true);
curl_setopt($ch,CURLOPT_POSTFIELDS, 'request=' . urlencode($post));
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/x-www-form-urlencoded']);
$res = curl_exec($ch);
?>

Struttura della risposta

La risposta è composta dai seguenti dati:

• code: valore di ritorno del comando. Maggiori informazioni sono disponibili nel capitolo Codici di ritorno.
• result: descrizione testuale del codice di ritorno.
• timestamp: ora di esecuzione del comando in formato UNIX.
• clTRID: identificatore del comando lato client.
• svTRID: identificatore del comando lato server.
• command: comando WAPI.
• data: valori di ritorno. Se il comando fallisce, i dati non vengono restituiti.
• test: viene inserito nella risposta ai comandi che contengono a loro volta questo indicatore.

Un esempio di risposta in formato JSON è il seguente:

{
  "response":
  {
    "code": "1000",
    "result": "ok",
    "timestamp": "1286356644",
    "svTRID": "1286356644.0246.21616",
    "command": "domain-create",
    "data": 		
    {
      "num": "1311000863",
      "expiration": "2011-10-06"
    },
    "test": "1"
  }
}

Stránkování a hledání v seznamech

Seznamové příkazy domains-list e nelle dns-rows-list mají nepovinné parametry pro hledání a stránkování. Když je nezadáte, WAPI vrátí odpověď stejně jako dosud, tedy celý seznam.

Parametry v části data požadavku:

• search: Hledaný text, bez rozlišení velikosti písmen. U domains-list se hledá v názvu domény, u dns-rows-list v názvu nebo datech záznamu.
• page: Číslo stránky od 1. Výchozí hodnota je 1.
• page_limit: Počet položek na stránku, nejvýše 1000 (větší hodnotu WAPI sníží na 1000). Když ho nezadáte nebo zadáte 0, WAPI vrátí všechny položky.

Comando dns-rows-list má navíc tyto filtry:

• row_name: Přesný název záznamu. Hodnota @ znamená záznam přímo na doméně.
• rdtype: Typ záznamu (A, AAAA, MX, TXT…), na velikosti písmen nezáleží.

Když zadáte kterýkoli z těchto parametrů, WAPI vrátí seznam jako pole (u domains-list v položce domain, u dns-rows-list v položce row) a v části data odpovědi doplní:

• total: Celkový počet položek po použití filtrů.
• page: Číslo vrácené stránky.
• page_limit: Použitý počet položek na stránku (0 znamená všechny).

Na co dát pozor:

• Stránka za koncem seznamu vrátí prázdný seznam s položkou total, ne chybu.
• Neplatnou hodnotu page oppure page_limit (text, záporné číslo) WAPI neodmítne, ale nahradí ji výchozí hodnotou: page 1, page_limit 0, tedy všechny položky.
• Pole místo hodnoty v page oppure page_limit vrátí chybu 2101.
• Comando dns-domains-list vrací total (jako řetězec), page e nelle page_limit vždy. Když page_limit nezadáte nebo zadáte 0, použije 1000.

Comando JSON domains-list (aktivní domény obsahující „example“, první stránka po dvou doménách), podrobný popis v dokumentaci příkazu domains-list ⧉:

{
  "request": {
    "user": "suo@login.tld",
    "auth": "stringa di autorizzazione generata",
    "command": "domains-list",
    "clTRID": "proprio codice id",
    "data": {
      "status": "active",
      "search": "example",
      "page": 1,
      "page_limit": 2
    }
  }
}

Comando JSON dns-rows-list (záznamy typu A domény example.cz, první stránka po 50 záznamech), podrobný popis v dokumentaci příkazu dns-rows-list ⧉:

{
  "request": {
    "user": "suo@login.tld",
    "auth": "stringa di autorizzazione generata",
    "command": "dns-rows-list",
    "clTRID": "proprio codice id",
    "data": {
      "domain": "example.cz",
      "rdtype": "A",
      "page": 1,
      "page_limit": 50
    }
  }
}

Notifiche

Le operazioni asincrone non possono essere eseguite immediatamente. L’avanzamento e il risultato di tali operazioni possono essere seguiti tramite le notifiche. Le richieste sincrone non utilizzano le notifiche.

Se WAPI non riesce a completare l’operazione subito, nella risposta restituisce Request pending (1001). Al termine dell’operazione (per le azioni più complesse, al termine dei singoli passaggi) crea una notifica, che è analoga alla risposta classica. La notifica può essere associata alla richiesta corrispondente tramite i parametri clTRID o svTRID.

I dati della notifica sono sempre codificati in UTF-8.

Le notifiche possono essere ricevute nei seguenti modi (in base all’impostazione scelta durante l’attivazione):

• Tramite la coda POLL.
• Tramite invio all’indirizzo e-mail indicato.
• Tramite protocollo HTTP (o HTTPS) all’indirizzo URL da Lei stabilito, con il metodo POST nel parametro request. Come consegna corretta viene considerata una risposta HTTP con codice di ritorno 200. Se la consegna non riesce, il nostro sistema riproverà a consegnare a intervalli di alcuni minuti.

Un esempio di notifica in formato JSON è il seguente:

{
  "notify": {
    "code": 1000,
    "result": "OK",
    "timestamp": 1286957932,
    "clTRID": "AvrX87Kqk6h3",
    "svTRID": "1286957874.1271.15706",
    "command": "ping-async",
    "ID": 2691
  }
}

Notifiche di sistema

Le notifiche di sistema inviano informazioni su eventi rilevanti, al momento solo sul trasferimento di un dominio presso un altro fornitore. Se per l’account è attivo WAPI, il sistema invia tale informazione tramite notifica, in modo analogo a un comando asincrono.

Il protocollo con cui WAPI invia le notifiche di sistema si imposta seguendo il capitolo Attivazione di WAPI nell’amministrazione clienti. Questa opzione vale per le notifiche inviate a un indirizzo e-mail o a un indirizzo URL. In caso di prelievo dalla coda POLL, la risposta ha la stessa forma del comando.

La struttura è la stessa della notifica classica, il comando (command) è sempre system-notify. Nel nodo data troverà poi informazioni più dettagliate.

---

Comandi di base

Tra i comandi di base rientrano ping, ping-async e i comandi per lavorare con la coda POLL poll-req e poll-ack.

ping

Il comando ping serve a verificare il funzionamento di WAPI, ad esempio delle credenziali di accesso, dell’indirizzo IP o del codice.

I valori di ritorno sono:

• 1000 – OK

Comando JSON:

{
  "request": {
    "user": "suo@login.tld",
    "auth": "stringa di autorizzazione generata",
    "command": "ping",
    "clTRID": "proprio codice id"
  }
}

Risposta JSON:

{
  "response": {
    "code": "1000",
    "result": "OK",
    "timestamp": "ora UTF",
    "clTRID": "proprio codice id",
    "svTRID": "codice id del server",
    "command": "ping"
  }
}

ping-async

Il comando ping-async verifica il funzionamento delle notifiche WAPI.

I valori di ritorno sono:

• 1000 OK
• 1001 Richiesta in attesa

Comando JSON:

{
  "request": {
    "user": "suo@login.tld",
    "auth": "stringa di autorizzazione generata",
    "command": "ping",
    "clTRID": "proprio codice id"
  }
}

Risposta JSON:

{
  "response": {
    "code": "1001",
    "result": "Request pending",
    "timestamp": "ora UTF",
    "clTRID": "proprio codice id",
    "svTRID": "codice id del server",
    "command": "ping"
  }
}

Notifica JSON:

{
  "notify": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "ora UTF",
    "clTRID": "proprio codice id",
    "svTRID": "codice id del server",
    "command": "ping-async",
    "id": "id per la coda POLL",
    "data": {
      "round": "numero del tentativo",
      "time": "ora",
      "done": 1
    }
  }
}

poll-req e poll-ack

Il prelievo delle notifiche dalla coda POLL si effettua combinando i comandi poll-req e poll-ack: 

1. Con il comando poll-req scarica la notifica disponibile più vecchia.
2. Con il comando poll-ack contrassegna la notifica come ricevuta e rende così disponibili quelle più recenti, fino all’esaurimento della coda.

I valori di ritorno per poll-req sono:

• 1000 – notifica ottenuta
• 1003 – nella coda non è presente alcuna notifica non letta
• 2150 – per il Suo account non è impostato il prelievo delle notifiche dalla coda POLL

Comando JSON poll-req:

{
  "request": {
    "user": "suo@login.tld",
    "auth": "stringa di autorizzazione generata",
    "command": "poll-req",
    "clTRID": "proprio codice id"
  }
}

Risposta JSON a poll-req (notifica disponibile):

{
  "response": {
    "code": “1000”,
    "result": "OK",
    "timestamp": "ora UTF",
    "clTRID": "proprio codice id",
    "svTRID": "codice id del server",
    "command": "poll-req",
    "data": {
      "notify": {
        "code": “1000”,
        "result": "OK",
        "timestamp": "ora UTF",
        "clTRID": "proprio codice id del comando trovato",
        "svTRID": "codice id del server per il comando trovato",
        "command": "nome del comando",
        "id": "id nella coda POLL"
      }
    }
  }
}

Risposta JSON a poll-req (coda di notifiche vuota):

{
  "response": {
    "code": 1003,
    "result": "Empty notifications queue",
    "timestamp": “1286962852”,
    "clTRID": "proprio codice id",
    "svTRID": "codice id del server",
    "command": "poll-req"
  }
}

Al comando poll-ack si forniscono i dati (parametri):

• id – ID della notifica POLL corrente

I valori di ritorno per poll-ack sono:

• 1002 – notifica contrassegnata come ricevuta
• 2151 – notifica non trovata

Comando JSON poll-ack:

{
  "request": {
    "user": "suo@login.tld",
    "auth": "stringa di autorizzazione generata",
    "command": "poll-ack",
    "clTRID": "proprio codice id",
    "data": {
      "id": “ID della notifica POLL ricevuta”
    }
  }
}

Risposta JSON a poll-ack:

{
  "response": {
    "code": “1002”,
    "result": "Notification acquired",
    "timestamp": "ora UTF",
    "clTRID": "proprio codice id",
    "svTRID": "codice id del server",
    "command": "poll-ack"
  }
}

---

Elenco dei codici di ritorno

I codici di ritorno nelle risposte e nelle notifiche Le aiuteranno a individuare l’andamento ed eventuali errori di WAPI.

Suddivisione di base dei codici di ritorno:

• 1xxx – il comando è stato eseguito correttamente.
• 2xxx – comando non corretto (ad esempio campi di input mancanti, formato o valore non corretto).
• 3xxx – errore dell’oggetto di destinazione – non è possibile eseguire l’azione richiesta, l’oggetto non si trova nello stato corretto (ad esempio nel tentativo di registrare un dominio già occupato, …).
• 4xxx – errore durante l’esecuzione del comando (ad es. registro dei domini non disponibile, errore di comunicazione, ecc.).
• 5xxx – errore interno o stato del nostro sistema.
• x0xx, x1xx – generale.
• x2xx – domini.
• x3xx – DNS.

Le risposte concrete restituite per un determinato comando si trovano sempre nella documentazione del comando.

---

Glossario

• Comando asincrono: comando eseguito per un tempo prolungato, restituisce solo un messaggio di accettazione; l’avanzamento successivo si segue tramite le notifiche.
• API: Application Programming Interface. Interfaccia che Le consente di ottenere dati o gestire un’applicazione di terze parti con codice proprio.
• Data: contenuto di alcuni comandi che specifica impostazioni dettagliate. La struttura dei dati è definita dal comando specifico.
• JSON: JavaScript Object Notation. Modalità moderna di comunicazione con le API.
• Codice di ritorno: Numero che identifica il tipo di risposta di WAPI a un comando.
• Notifiche: codice JSON o XML con messaggi sull’avanzamento di un comando asincrono.
• Comando: richiesta a WAPI.
• Comando sincrono: comando eseguito praticamente all’istante. Restituisce una risposta completa e non utilizza le notifiche.
• Notifiche di sistema: tipo speciale di notifiche su eventi nel sistema, che WAPI invia automaticamente nel formato impostato.
• UTF-8: Unicode Transformation Format. Diffuso standard internazionale di codifica dei caratteri che supporta un gran numero di alfabeti.
• WAPI: interfaccia per la gestione di alcune parti dell’amministrazione clienti (conto prepagato, domini, DNS).
• XML: eXtended Markup Language. Modalità più datata di comunicazione con le API.

Questo articolo le è stato utile?

Il suo giudizio ci aiuta a migliorare i nostri articoli.

SìNo

Desidera scriverci qualcosa su questo articolo? (facoltativo)

Il suo messaggio viene letto dal team della documentazione, che però non risponde. Se ha bisogno di aiuto, contattici tramite il modulo di contatto. Non inserisca password né dati personali.

Lasci vuoto questo campo