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
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
}
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