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