Gestire la risposta

Codici di risposta (HTTP Status Code)

Per ogni richiesta le HTTP API restituiscono uno dei seguenti HTTP Status Code:

200 - Richiesta completata correttamente

400 - Parametro mancante o autenticazione fallita

404 - Risorsa non trovata

405 - Metodo HTTP non consentito

500 - Errore imprevisto del server

Contenuto risposta

Ad ogni chiamata HTTP GET completata con successo (HTTP status uguale a 200) le REST API restituiscono come contenuto un JSON/XML.

Se una chiamata dovesse terminare con un errore (HTTP status diverso da 200) viene resituito un JSON/XML esplicativo dell'errore:

errorCode - Codice HTTP status

errorMsg - Codice di errore esplicativo del problema occorso

Ad esempio nel caso l'autenticazione fallisca le REST API restituiscono un HTTP Status 400 e come contenuto:

{
   "errorMsg":"BAD_CREDENTIALS",
   "errorCode":400
}

Paginazione

Alcune risorse (ricerca sms inviati o ricevuti,ricerca contatti, etc.) restituiscono i risultati paginati.

Ad esempio la ricerca sms inviati restiruisce il seguente JSON

{
   "metadata":{
      "count":1,
      "offset":0,
      "limit":20
   },
   "smsList":[
      {
         "id":389395385,
         "to":"393480000000",
         "text":"Test Sms",
         "from":"mrossi",
         "status":"DELIVERED",
         "insertDate":"2014-01-13T15:01:35+0100",
         "sentDate":"2014-01-13T15:01:37+0100",
         "deliveryDate":"2014-01-13T15:01:40+0100",
         "transactionId":"72810108d4114097b9edb42b255b273c",
         "price":0.0945
      }
   ]
}

Il campo metadata contiene le informazioni utili a gestire la paginazione dei risultati.

La proprietà count indica il numero totale di risultati trovati per quella ricerca.

I campi offset e limit indicano rispettivamente l'indice del primo risultato ed il numero di risultati restituiti dalla chiamata.

Offset e limit possono essere usati come parametri nella richiesta in modo da controllare il range di risultati restituiti.

Ad esempio se una ricerca trova 100 risultati e la dimensione della pagina è di 20 elementi

{
   "metadata":{
      "count":100,
      "offset":0,
      "limit":20
   },
   .......
}

sarà possibile ottenere 5 pagine usando i seguenti valori di offset e limit:

pagina 1 - offset=0&limit=20
pagina 2 - offset=20&limit=20
pagina 3 - offset=40&limit=20
pagina 4 - offset=60&limit=20
pagina 5 - offset=80&limit=20