Indice
Introduzione
Il modulo serve per esporre dei web services utilizzando la modalità REST. E' presente nella cartella 'wsrest' all'interno di '/lib'.
Definizione routes
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)
- CONTROLLER: è il nome della classe controller (presente in '/controller') esclusa l'estensione ('.php')
- ACTION: è il nome del metodo (public) del controller da invocare
- OUTPUT: indica il formato dell'output (xml/json)
- CHECKAUTH: indica se la chiamata deve essere autenticata (se 1 = controlla autenticazione, altrimenti 0)
Esempio
[dummyActionGET] VERB = GET CONTROLLER = dummyController ACTION = dummyActionGET OUTPUT = json CHECKAUTH = 1
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
public function dummyActionGET($params) {
$toReturn = array(
'chiave1' => 'valore1',
'chiave2' => 'valore2',
'params' => array()
);
if ($params != null) {
$toReturn['params'] = $params;
}
return $toReturn;
}
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
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:
{
"PKVALUES": {
"CODGRNAZ":"01"
}
}
Risposta:
{
"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"
}
}
}
count
Effettua il conteggio dei record, dati in ingresso i parametri per la query specifica.
Chiamata:
{
"PARAMS": {
"DESGRNAZ":"europ"
}
}
Risposta:
{
"ESITO": 1,
"MESSAGGIO": "Esito positivo",
"DATI": {
"COUNT": "2"
}
}
query
Effettua la lettura dei record, dati in ingresso i parametri per la query specifica.
Chiamata:
{
"PARAMS": {
"DESGRNAZ":"europ"
},
"FROM": 0,
"TO": 2
}
Risposta:
{
"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"
}
]
}
}
insert
Chiamata:
{
"DATA": {
"CURRENTRECORD":{
"CODGRNAZ": "90",
"DESGRNAZ": "Inserimento da WS",
"CEENAZ":"C",
"CONTINENTE":"1"
}
}
}
Risposta:
{
"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"
}
}
}
update
Chiamata:
{
"DATA": {
"CURRENTRECORD":{
"CODGRNAZ": "90",
"DESGRNAZ": "Inserimento da WS Modificato",
"CEENAZ":"E",
"CONTINENTE":"1"
}
}
}
Risposta:
{
"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"
}
}
}
delete
Chiamata:
{
"DATA": {
"CURRENTRECORD":{
"CODGRNAZ": "90",
"DESGRNAZ": "Inserimento da WS",
"CEENAZ":"C",
"CONTINENTE":"1"
}
}
}
Risposta:
{
"ESITO": 1,
"MESSAGGIO": "Esito positivo",
"DATI": {
"RESULTS": {
"CODGRNAZ": "90",
"DESGRNAZ": "Inserimento da WS",
"CEENAZ": "C",
"CONTINENTE": "1"
}
}
}
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:
{
"METHOD":"testCustom",
"PARAMS":{
"PAR1": "X",
"PAR2": 1
}
}
Risposta:
{
"ESITO": 1,
"MESSAGGIO": "Esito positivo",
"DATI": {
"RESULTS": {
"Risposta metodo custom": {
"Parametro 1": "X",
"Parametro 2": 1
}
}
}
}