REST API 2

The REST API permette di scambiare i dati (anche sensibili) tramite protocollo sicuro ed architettura RESTful

Tutti i serivizi a disposizione sono effettuati utilizzando Java J2EE. Tuttavia è possibile usera Curl / Python / PHP / Golang / Ruby / Swift / Objective-C / Rust / Scala / C# o altri linguaggi di programmazione. Gli esempi lato client di questa documentazione sono forniti in Jquery

Sicurezza

Quando si chiama questo WebServer di produzione, assicurarsi che sia in esecuzione tramite HTTPS e che abbia un certificato SSL valido. Il metodo di accesso richiede di pubblicare il Authentication Token e Id-User in chiaro, motivo per cui consigliamo vivamente di chiamare l'API di accesso REST su HTTPS. Inoltre:

• Chiatate esclusivamente gestite in protocollo HTTPS
• Strategia di scadenza IDCALL di autorizzazione servizi
• Ogni servizio richiamato in lettura o scrittura deve essere processato tramite Authentication Token e Id-User
• Il web server accetta metodi com GET, POST a seconda della finalità del servizio. (i metodi DELETE E PUT sono stati deprecati secondo protocollo HTML 5 W3.org Methods
• Ogni richiesta di lettura o scrittura avviene richiamando un servizio dedicato con un URL prestabilito (es. /api/v1.0/get_driver)
• Ogni chiamata prevede la completa gestione degli errori sia come status di risposta che come descrizione della tipologia di eccezione.

HEADER IMPLICITI (Autenticazione di Provenienza)

A parte alcuni servizi descrittivi di sistema (elenco stati errore, elenco servizi presenti, versione corrente etc..) ogni chiamata necessita di chiavi Request Header:

• X-Auth-Token: Rappresenta l'identificativo univoco del client che fa la richiesta (tipicamente rappresenta un azienda, un portale etc)
• X-User-Id: Rappresenta l'identificativo univoco dell'utenza del client che fa la richiesta (tipicamente rappresenta un user dell'azienda, un portale etc)

Ogni chiamata prevede obbligatoriamente l'invio di questi due parametri come request header indipendentemente dalla richiesta del token ID CALL necessario per accedere ai servizi.

      $.ajax({
            type: 'POST',
            contentType: 'application/json',
            url: 'https://wb.locautorent.com/api/v1.0/get_auth',
            processData: false,
            beforeSend: function (xhr) {
                        xhr.setRequestHeader("X-Auth-Token",'2314120938redadflasdhkjavfsdfgs');
                        xhr.setRequestHeader("X-User-Id",'dfsflksjòlkj');
            }, success: function (data) {
            ......
           }
      })

ID CALL (Autenticazione Operativa)

Prima di accedere ad ogni servizio per il quale è finalizzato uno scambio dati (sia in lettura che in scrittura) il sistema rilascia al client durante l'autenticazione un token denominato ID CALL grazie al quale sara possibile effetturare le varie richieste fino alla scadenza temporale di tale token (tipicamente dopo secondi/minuti il parametro è trasmesso nella risposta come "expired_id_call") . Una volta che il Token ID CALL risulta scaduto basterà richiederne uno successivo fino a necessità. Nel caso il token sia ancora valido il sistema può decidere di reinviarlo tale per efficentare la procedura. Per motivi di sicurezza la richiesta di ID CALL sarebbe conveniente invocarla prima di ogni richiesta servizio.

Esempio di Chiamata

       $.ajax({
            type: 'POST',
            contentType: 'application/json',
            url: 'https://wb.locautorent.com/api/v1.0/get_auth',
            processData: false,
            beforeSend: function (xhr) {
                        xhr.setRequestHeader("X-Auth-Token",'2314120938redadflasdhkjavfsdfgs');
                        xhr.setRequestHeader("X-User-Id",'dfsflksjòlkj');
            }, success: function (data) {
                  var id_call=data.id_call
           }
      })

Esempio di Risposta

      {
        "Auth": {
          "id_call": "oRK70XC6VvnkKqrBuaF7Clmee",
          "expired_id_call": 60,
          "iduser": 1,
          "ts": "2020-06-24 21:43:29.235367"
        }
      }

Gestione Errori

Il webserver RESTFul implementa la gestione completa degli errori impostando lo status della risposta in base alla alla riuscita o fallimento della richiesta (vedi tabella codici errore). La risposta in caso di errore è sempre di tipo JSON e sarà strutturata come segue:

• Error ID: codice univoco errore.
• Message: Messaggio predefinito in base all'eccezione scatenata.
• Error: Descrizione dell'errore
• Status: Status di risposta (implicito nella response HTTP)
• Code: codice Errore Interno

Esempio di Risposta di Errore

{
  "errorId": "908422181786565330",
  "message": "Authentication Profile Not Found",
  "error": "Token doesn't belong to specified user.",
  "status": 402
}

Codifica Status Errori

Di seguito la tabella riporta i vari Error Status HTTP restituiti ed il metodo gestito.

JSON FORMAT

Il webServer RESTFul gestira qualsiasi tipo di risposta in formato Standard JSON (JavaScript Object Notation). A meno che il servizio debbe rispondere con un solo data-record le risposte saranno gestite secondo la struttura ad array. E' possibile richiedere al server due differenti tipi di formattazione JSON:

• JSON: i dati vengono rappresentati secondo la classica tabella di HASH (chiave-valore).
• JSON-DataSet: i dati vengono rappresentati secondo due array. Il primo ("columns") rappresenta il nome delle colonne ed il secondo ("dataset") i valori.

La scelta di tale formato può essere fatta dal client durante la chiamata tramite l'header "Accept": xhr.setRequestHeader("Accept", 'JSON-DataSet');

Esempio di Risposta JSON

      {
        "response": [
          {
            "cognome": "Rossi",
            "black_list": false,
            "nazione": "IT - ITALIA",
            "idconducente": 123456,
            "nome": "Mario"
          }
        ]
      }

Esempio di Risposta JSON-DataSet

      {
        "response": {
          "columns": [
            "idconducente",
            "cognome",
            "nome",
            "nazione",
            "black_list"
          ],
          "dataset": [
            {
              "0": 123456,
              "1": "Rossi",
              "2": "Mario",
              "3": "IT - ITALIA",
              "4": false
            }
          ]
        }
      }