Differenze

Queste sono le differenze tra la revisione selezionata e la versione attuale della pagina.

--- sviluppo:rest_server [2016/02/29 08:53] – creata m.biagioli
+++ sviluppo:rest_server [2024/10/15 09:45] (versione attuale) – modifica esterna 127.0.0.1
@@ Linea 1: / Linea 1: @@
-==Introduzione==
+======Introduzione======
 Il modulo serve per esporre dei web services utilizzando la modalità REST.
 E' presente nella cartella 'wsrest' all'interno di '/lib'.
-==Definizione routes==
+======Definizione routes======
-Le routes vanno censite su un apposito file di configurazione: '/config/routes.ini'.
+Le routes vanno censite su appositi file di configurazione con estensione '.ini' all'interno della cartella 'routes'.
 Per ogni route devono essere specificate le seguenti informazioni:
-  * VERB: indica il 'verb http' (GET o POST)
+  * **VERB**: indica il 'verb http' (GET o POST)
-  * CONTROLLER: è il nome della classe controller (presente in '/controller') esclusa l'estensione ('.php')
+  * **CONTROLLER**: è il nome della classe controller (presente in '/controller') esclusa l'estensione ('.php')
-  * ACTION: è il nome del metodo (public) del controller da invocare
+  * **ACTION**: è il nome del metodo (public) del controller da invocare
-  * OUTPUT: indica il formato dell'output (xml/json)
+  * **OUTPUT**: indica il formato dell'output (xml/json)
-  * CHECKAUTH: indica se la chiamata deve essere autenticata (se 1 = controlla autenticazione, altrimenti 0)
+  * **CHECKAUTH**: indica se la chiamata deve essere autenticata (se 1 = controlla autenticazione, altrimenti 0)
-Esempio:
+=====Esempio=====
+<code>
 [dummyActionGET]
 VERB = GET
@@ Linea 19: / Linea 21: @@
 OUTPUT = json
 CHECKAUTH = 1
+</code>
+======Controller======
+Il controller ha il compito di gestire la chiamata.
+Per ogni controller possono essere presenti più 'actions'.
+Ogni 'action' corrisponde ad un metodo 'public', che riceve in ingresso un array di parametri.
+Ogni controller estende la classe padre 'RestController'.
+Ogni 'action' deve restituire un risultato (sarà poi compito del server REST formattare adeguatamente l'output).
+=====Esempio di una action=====
+<code>
+public function dummyActionGET($params) {
+	$toReturn = array(
+		'chiave1' => 'valore1',
+		'chiave2' => 'valore2',
+		'params' => array()
+	);
+	if ($params != null) {
+		$toReturn['params'] = $params;
+	}
+	return $toReturn;
+}
+</code>
+======Autenticazione======
+Nel file 'routes.ini' sono presenti i seguenti metodi per la gestione dell'autenticazione:
+  * **GetItaEngineContextToken**: date in input le credenziali per il login, restituisce un token di autenticazione che dovrà essere utilizzato per tutte le chiamate successive autenticate.
+  * **CheckItaEngineContextToken**: controlla la validità del token in input.
+  * **DestroyItaEngineContextToken**: cancella il token indicato in input dalla sessione.
+=====Esempio di chiamata per ottenere un token di autenticazione=====
+http://localhost:4000/itaTest/wsrest/service.php/login/GetItaEngineContextToken?UserName=italsoft&Password=DemoPal1&DomainCode=X999
+=====Chiamate autenticate=====
+Per le chiamate autenticate deve essere passato nell'header HTTP della request il parametro **X-ITA-TOKEN**, che deve contenere il token ottenuto dalla chiamata '**GetItaEngineContextToken**' (il token deve essere valido e non scaduto).
+======Multipart Request======
+Per le richieste multipart, l'unica differenza rispetto alle altre chiamate è che nell'array dei parametri in input della action viene passata la chiave 'FILES' di tipo array, che contiene l'elenco dei file (corrisponde alla variabile superglobal '$_FILES')
+======REST Model======
+Per le classiche operazioni CRUD su un model attraverso l'utilizzo di servizi REST (ad esempio, se si vuole utilizzare itaEngine come back-end completo di una app implementata con un'altra tecnologia - come AngularJS o Ionic).
+Le operazioni messe a disposizione sono le seguenti:
+  * load [GET]
+  * count [GET]
+  * insert [POST]
+  * update [POST]
+  * delete [POST]
+  * custom [POST]
+Le operazioni CRUD sono associate al model, se presente la classe specifica viene presa quella, altrimenti si va in fallback sulla classe generica, che deriva da wsModelRest.
+Esempio:
+Modello: cwbBtaGrunaz.php
+Classe ModelRest specifica: rest/cwbBtaGrunazModelRest.php
+(Fallback su rest/cwbBaseModelRest)
+=====load=====
+Effettua la ricerca di un record per chiave.
+Riceve in ingresso i valori delle PK.
+Chiamata:
+<code>
+{
+	"PKVALUES": {
+		"CODGRNAZ":"01"
+	}
+}
+</code>
+Risposta:
+<code>
+{
+  "ESITO": 1,
+  "MESSAGGIO": "Esito positivo",
+  "DATI": {
+    "RESULTS": {
+      "CODGRNAZ": "01",
+      "DESGRNAZ": "UNIONE EUROPEA                          ",
+      "CEENAZ": "C",
+      "CONTINENTE": "1 ",
+      "CODUTE": "italsoft            ",
+      "DATAOPER": "2015-12-15",
+      "TIMEOPER": "17:38:18"
+    }
+  }
+}
+</code>
+=====count=====
+Effettua il conteggio dei record, dati in ingresso i parametri per la query specifica.
+Chiamata:
+<code>
+{
+	"PARAMS": {
+		"DESGRNAZ":"europ"
+	}
+}
+</code>
+Risposta:
+<code>
+{
+  "ESITO": 1,
+  "MESSAGGIO": "Esito positivo",
+  "DATI": {
+    "COUNT": "2"
+  }
+}
+</code>
+=====query=====
+Effettua la lettura dei record, dati in ingresso i parametri per la query specifica.
+Chiamata:
+<code>
+{
+	"PARAMS": {
+		"DESGRNAZ":"europ"
+	},
+	"FROM": 0,
+	"TO": 2
+}
+</code>
+Risposta:
+<code>
+{
+  "ESITO": 1,
+  "MESSAGGIO": "Esito positivo",
+  "DATI": {
+    "RESULTS": [
+      {
+        "CODGRNAZ": "01",
+        "DESGRNAZ": "UNIONE EUROPEA                          ",
+        "CEENAZ": "C",
+        "CONTINENTE": "1 ",
+        "CODUTE": "italsoft            ",
+        "DATAOPER": "2015-12-15",
+        "TIMEOPER": "17:38:18"
+      },
+      {
+        "CODGRNAZ": "02",
+        "DESGRNAZ": "ALTRI PAESI EUROPEI                     ",
+        "CEENAZ": "E",
+        "CONTINENTE": "1 ",
+        "CODUTE": "italsoft            ",
+        "DATAOPER": "2016-01-22",
+        "TIMEOPER": "10:25:21"
+      }
+    ]
+  }
+}
+</code>
+=====insert=====
+Chiamata:
+<code>
+{
+	"DATA": {
+		"CURRENTRECORD":{
+			"CODGRNAZ": "90",
+			"DESGRNAZ": "Inserimento da WS",
+			"CEENAZ":"C",
+			"CONTINENTE":"1"
+		}
+	}
+}
+</code>
+Risposta:
+<code>
+{
+  "ESITO": 1,
+  "MESSAGGIO": "Esito positivo",
+  "DATI": {
+    "RESULTS": {
+      "CODGRNAZ": "90",
+      "DESGRNAZ": "Inserimento da WS                       ",
+      "CEENAZ": "C",
+      "CONTINENTE": "1 ",
+      "CODUTE": "italsoft            ",
+      "DATAOPER": "2016-06-24",
+      "TIMEOPER": "15:07:10"
+    }
+  }
+}
+</code>
+=====update=====
+Chiamata:
+<code>
+{
+	"DATA": {
+		"CURRENTRECORD":{
+			"CODGRNAZ": "90",
+			"DESGRNAZ": "Inserimento da WS Modificato",
+			"CEENAZ":"E",
+			"CONTINENTE":"1"
+		}
+	}
+}
+</code>
+Risposta:
+<code>
+{
+  "ESITO": 1,
+  "MESSAGGIO": "Esito positivo",
+  "DATI": {
+    "RESULTS": {
+      "CODGRNAZ": "90",
+      "DESGRNAZ": "Inserimento da WS Modificato            ",
+      "CEENAZ": "E",
+      "CONTINENTE": "1 ",
+      "CODUTE": "italsoft            ",
+      "DATAOPER": "2016-06-24",
+      "TIMEOPER": "15:18:11"
+    }
+  }
+}
+</code>
+=====delete=====
+Chiamata:
+<code>
+{
+	"DATA": {
+		"CURRENTRECORD":{
+			"CODGRNAZ": "90",
+			"DESGRNAZ": "Inserimento da WS",
+			"CEENAZ":"C",
+			"CONTINENTE":"1"
+		}
+	}
+}
+</code>
+Risposta:
+<code>
+{
+  "ESITO": 1,
+  "MESSAGGIO": "Esito positivo",
+  "DATI": {
+    "RESULTS": {
+      "CODGRNAZ": "90",
+      "DESGRNAZ": "Inserimento da WS",
+      "CEENAZ": "C",
+      "CONTINENTE": "1"
+    }
+  }
+}
+</code>
+=====custom=====
+Attraverso il metodo custom è possibile chiamare qualsiasi metodo della classe modelRest specifica.
+Il servizio riceva in ingresso il nome del metodo e i parametri.
+Chiamata:
+<code>
+{
+	"METHOD":"testCustom",
+	"PARAMS":{
+		"PAR1": "X",
+		"PAR2": 1
+	}
+}
+</code>
+Risposta:
+<code>
+{
+  "ESITO": 1,
+  "MESSAGGIO": "Esito positivo",
+  "DATI": {
+    "RESULTS": {
+      "Risposta metodo custom": {
+        "Parametro 1": "X",
+        "Parametro 2": 1
+      }
+    }
+  }
+}
+</code>{{counter}} visualizzazioni.