Servizi REST su ESSE3

Descrizione Generale

I servizi REST di ESSE3 offrono l'accesso ai dati dell'applicativo seguendo i seguenti principi:

• Coerenza: la documentazione deve essere coerente con l'implementazione dei servizi
• Sicurezza: ogni utente accede solo ai dati per i quali risulta abilitato
• Uniformità: la medesima struttura dati deve essere corerente tra i vari ENDPOINT

Per garantire questi obbiettivi viene utilizzato il Tool Swagger (http://swagger.io) che consente di incentrare il processo di sviluppo partendo dalle specifiche dei servizi e dalla documentazione degli stessi.

La documentazione viene pertanto generata in modo dinamico utilizzando questo tool e risulta disponibile sul path relativo e3rest/docs rispetto all'installazione di WEBESSE3 dell'ateneo (questo garantisce il vincolo di coerenza).

La documentazione si presenta nel seguente modo:

La combo-box in alto alla pagina consente di selezionare i servizi disponibili: una volta selezionato un servizio vengono visualizzate gli endpoint (URI) che consentono di manipolare le risorse.

I servizi vengono rilasciati su aree del prodotto omogenee (libretto studente, calendario esami, struttura didattica ecc.) e consentono all'utente di poter navigare i servizi disponibili filtrandoli in modo opportuno.

L'interfaccia consente di prendere visione dei dettagli dei vari URI esposti da una API 

La sezione 1 contiene la documentazione generica del singolo endpoint ed eventuali particolarità da tenere in considerazione durante l'utilizzo del servizio.

La sezione 2 specifica l'accesso ai dati garantito dal sistema rispetto agli utenti collegati; vengono descritte le tipologie di utenti che sono abilitati all'accesso al servizio e le condizioni a contorno di filtro dei dati della classe di modello che ne caratterizzano i permessi.
Controllando il caso specifico di esempio, gli utenti che possono accedere all'endpoint di recupero degli appelli sono i seguenti

• DOCENTE : visualizza i soli appelli che coincidono con le abilitazioni a lui assegnate dalla maschera "Abilita Docenti"
• STUDENTE: visualizza gli appelli collegati alle attività del libretto

Il punto 3 consente di avere un esempio dei possibili dati ritornati dal metodo (per avere un'idea della struttura generale), è anche possibile, tramite il link Model, visualizzare la descrizione della classe di modello con il dettaglio di ogni singolo campo come visualizzato nella figura sottostante

Seguono tutti i possibili parametri previsti dal metodo ed infine c'è la possibilità di invocare il metodo in modo interattivo tramite il punto 4 (con i parametri impostati) per verificare il recupero effettivo dei dati.

In particolare la sezione 2 consente di stabilire delle politiche di accesso ai dati per ogni URI che garantiscono la sicurezza che i dati recuperati siano sempre di competenza dell'utente loggato.

Configurazione Client SWAGGER per OAUTH2

Questa sezione descrive la configurazione del client SWAGGER con un server OAUTH.  In particolare viene utilizzata l'implementazione del M.I.T (MiTREid)

1. Loggarsi sul server OAUTH con una utenza amministativa
2. Creare una nuova applicazione client
   
3. impostare il clientID a swagger_esse3. E' comunque possibile cambiare clientId ma il default sul swagger utilizza questo valore
4. inserire l'url di redirect. L'url corretta è data dall'URL del client SWAGGER più o2c.html. Ad esempio se il client swagger è raggiungibile su https://unielearning.esse3.pp.cineca.it/e3rest/docs/ la corretta redirectUrl è https://unielearning.esse3.pp.cineca.it/e3rest/docs/o2c.html
5. salvare 
   

1. nel tab access 
   1. selezionare il flow implicit su Grant types
   2. selezionare token. id_token su Response Types
   3. salvare

1. Nel tab Credenziali 
   1. selezionare nessuna autenticazione
   2. salvare

Occorre poi impostare il seguente parametri di configurazione su ESSE3

• OAUTH_AUTHORIZATION_URL => <url del server oauth> + /oauth2/authorize
• OAUTH_JWK_KEYS => <url del server oauth> + /oauth2/jwk

Ad esempio per il server 

https://unielearning.openid.pp.cineca.it  gli URL Corretti sono i seguenti

• OAUTH_AUTHORIZATION_URL =>https://unielearning.openid.pp.cineca.it/oauth2/authorize
• OAUTH_JWK_KEYS => https://unielearning.openid.pp.cineca.it/oauth2/jwk

L'autenticazione con il server oauth avviene tramite un token JWT. Per effettuare il binding con l'utente di esse3 viene utilizzato l'attributo sub presente nel payload firmato del token. E' tuttavia possibile modificare il binding con un attributo differente impostando il valore da leggere nel parametro di configurazione OAUTH_USER_CLAIM.

Gestione permessi per Utenze Tecniche

Tra le varie tipologie di utenze previste dai servizi REST viene individuato un particolare gruppo di "utenze tecniche" che ha accesso a qualsiasi risorsa di una API dove questa risulta associata.

Questo gruppo ha lo scopo di gestire i casi d'uso "Server to Server" dove il client che usufruisce del servizio REST si trova su una macchina ad accesso ristretto (tipicamente un server BFF - Backend For Frontend) ed effettua i recuperi delle risorse a prescindere dai permessi sul loro accesso da parte di uno specifico utente. In questa architettura il BFF ha l'onere di garantire l'accesso alle risorse corrette per ogni utente e la logica prevista nei servizi REST di esse3 non viene utilizzata.

Al fine di rendere più granulare la gestione dei permessi (supponendo di dover autorizzare diversi BFF all'accesso ai servizi REST) dalla versione 18.08.01.00 di ESSE3 è possibile definire differenti gruppi di utenze tecniche alle quali abilitare l'accesso alle API.

La configurazione dei permessi avviene tramite la maschera "Gruppi/Funzioni/Utenti" del client di ESSE3.

Il gruppo 16 originario funge da gruppo "superuser" al quale vengono associate in automatico dal sistema tutte le funzioni disponibili con tutti i permessi.

E' possibile creare differenti gruppi per mappare altri utenti tecnici con minori permessi e/o disabilitare le abilitazioni al gruppo 16. Bisogna tenere in considerazione che eventuali nuove API rilasciate saranno abilitate in automatico al gruppo 16.

Per creare un nuovo gruppo occorre effettuare le seguenti operazioni

1. Inserire una nuova testata e marcare il gruppo con il flag UTENTE TECNICO REST 
2. Abilitare la funzione "SI_18_AREA_SOGEST" al nuovo gruppo creato
3. Sul tab "Tipi Client utilizzabili" aggiungere REST
4. Abilitare le API che il gruppo deve utilizzare: esiste una funzione REST_* per ogni item del menu a tendina presente nella documentazione dei servizi REST
5. Opzionale: selezionata una singola API i permessi valgono per tutte le risorse che vi sono contenute, nel caso si voglia modificare i permessi di una singola risorsa è possibile inserire gli override nella sezione sui blocchi sotto la lista delle funzioni

I permessi si mappano con i seguenti metodi HTTP

• Recupera => GET
• Nuovo => POST
• Modifica => PUT
• Cancella => DELETE 

In questo modo è possibile abilitare solo alcuni metodi in modo puntuale, Il flag abilita disabilita tutti gli accessi per tutti i metodi HTTP,

API-KEY

E3Rest prevede l'utilizzo delle API-KEY per poter identificare gli applicativi chiamanti e limitare l'utilizzo delle api alle sole applicazioni censite.
L'utilizzo della sola API-KEY di per sé non consente l'accesso, che dev'essere accompagnata dalle credenziali utente tramite uno dei metodi di autenticazione (basic o jwt) in modo da poter identificare l'utente (tecnico o non).

E' possibile abilitare la gestione delle API-KEY tramite il parametro di configurazione di esse3 REST_API_KEY_STRICT_MODE impostando il valore ad 1.

Una volta abilitato il parametro di configurazione tutte le chiamate autenticate richiedono il passaggio della api-key da parte dell'applicazione che invoca i servizi rest. 

Le modalità di passaggio sono specificate nella documentazione della API di autenticazione, consultare la documentazione relativa per i dettagli.

Provisioning delle API-KEY

Per Creare una nuova Api-KEY è possibile utilizzare la mashera di esse3 "Gestione API-KEY per i servizi REST" 

Per poter creare una nuova api-key da rilasciare ad una nuova applicazione occorre

1. creare un soggetto esterno che sia il referente dell'applicazione in questione, 
   
   è particolarmente importante indicare:
   tipo soggetto esterno (che deve essere APIKEY)
   email (per eventuali comunicazioni via mail riguardo alle api REST)
2. Inserire la riga della API-KEY indicando il soggetto esterno referente dell'applicazione lo stato della api-key (b-bozza, a-attivo) e il nome dell'applicazione
3. Nel dettaglio è possibile indicare quali sono gli utenti tecnici e/o i gruppi utente che possono utilizzare l'api-key generata a seconda della modalità di autenticazione prevista per l'applicazione

NB. Si sconsiglia di utilizzare lo stesso utente tecnico per più applicazioni.

E' possibile disattivare temporaneamente l'api-key rilasciata tramite il cambio dello stato dell'api-key stessa

Utilizzo dei servizi 

Sessione Applicativa

Tutti i servizi REST di ESSE3 si basano su una sessione applicativa da creare tramite il servizio di AUTENTICAZIONE (AUTH Api) che è descritto, al pari degli altri servizi, visualizzabile dalla combo-box in testa alla documentazione. 

La sessione applicativa si basa sulla basic-authentication (è necessario quindi fornire l'header Authentication su ogni richiesta che deve essere autenticata); la sessione tipica di utilizzo prevede le seguenti chiamate

1. chiamata al servizio di login (fn_login) tramite l'enpoint /login: questo servizio fornisce i principali dati dell'utente e le principali chiavi applicative di carriera nel caso questo sia uno studente
2. chiamate ai servizi autenticati (avendo cura di passare il cookie di sessione con il jsessionid ritornato e l'header di autenticazione richiesto dalla basic authentication)
3. chiamata al servizio di logout

Throttling delle chiamate

E' attivo un servizio di throttling per limitare il numero di chiamate per sessione in un intervallo di tempo previsto: il default prevede il limite di 60 chiamate al minuto per sessione.

E' possibile modificare questa impostazione tramite i parametri di esse3

• REST_REQ_SEC_WINDOW_LIMIT : imposta la dimensione dell'intervallo temporale in cui possono essere effettuate le chiamate
• REST_MAX_REQ_IN_WINDOW: imposta il numero massimo di chiamate nella finestra temporale impostata
• REST_MAX_REQ_IN_WINDOW_USER_TECNICO: imposta il numero massimo di chiamate nella finestra temporale impostata per gli utenti tecnici

gli stessi parametri sono anche disponibili per GRUPPO di utenti (p18_grp) nei campi REST_MAX_REQ_WINDOW e REST_NUM_REQ_WINDOW. Se questi campi sono valorizzati allora i valori per il gruppo sono sostiuiti ai valori dei parametri

Ad ogni richiesta il sistema risponde con degli header per indicare la client lo stato delle chiamate nella finestra indicata

  xratelimitreset:  numero di secondi prima che la finestra temporale si resetti
  xratelimitremaining: numero di invocazioni rimanenti nella finestra temporale
  xratelimitlimit: limite massimo di invocazioni previste nella finestra temporale

Filtri sull IP

E' possibile impostare dei filtri sugli IP per limitare l'accesso alle API. Analogamente ai filtri presenti su WEBESSE3 sono stati definiti dei parametri di configurazione per controllare questa funzionalità.

I filtri attualmente utilizzati sono i seguenti

**NOTA

Errore - "L'ip non è tra quelli abilitati all'accesso alla risorsa richiesta"

Qualora siano stati impostati  i parametri di IP_FILTER con gli IP da abilitate e si continua ad ottenere l'errore in oggetto, occorre verificare che l'indirizzo IP inserito nel parametro IP_FILTRO corrisponda poi all'indirizzo IP pubblico con cui il chiamante alla libreria ApiRest di ESSE3 è attestato su intrnet (verificare eventuali natting interni di rete tra ip-privato ed ip-pubblico).

Per verificare quale sia l'IP pubblico con cui "esce su internet"  la postazione del chiamante, accedere dalla postastione del chiamante alla action Versione.do del webESSE3 (https://<<url-base-webesse3>>/Versione.do), verificando il contenuto del campo RemoteAddess.

Caching delle richieste

E' attivo un servizio di caching delle response per garantire una maggiore prontezza delle risposte ed una maggiore affidabilità. Le cache disponibili sono due:

1. cache http: è implementata tramite gli header HTTP standard e consente ai client compatibili (principalmente i browser, ma anche i client utilizzati nel codice) di implementare un livello di cache sul client
2. cache server: è implementata tramite il caching delle response nel server, risulta indipendente dall'implementazione del client.

Ogni endpoint ha un livello di cache associato (il valore risulta visualizzato nella documentazione nella sezione delle estensioni dell'operation sotto in nome di x-cache-type).

I valori della cache sono i seguenti

Il tempo di permanenza di un item nella cache varia a seconda del livello associato e in base ad un moltiplicatore che è possibile configurare tramite paramento di configurazione:

• REST_HTTP_CACHE_MULT: impostato di default a 60 ==> si ottengono quindi i tempi di retention di (5 sec, 1min, 15 min e 1h)
• REST_SERVER_CACHE_MULT: impostato di default a 60 ==> si ottengono quindi i tempi di retention di (5 sec, 1min, 15 min e 1h)

Impostando a ZERO un moltiplicatore si disabilita la cache relativa.

E' possibile anche disabilitare la cache per sessione tramite l'enpoint /login/cache che consente di disattivare temporaneamente i moltiplicatori per quella cache.

Endpoint collegati

tramite l'header di request x-esse3-endpoint-relations è possibile richiedere la lista degli endpoint collegati all'operazione che hanno delle risorse collegate che devono essere resettate.

Con le SPA (Single Page Application) infatti i recuperi normalmente vengono salvati dal browser nella cache, e quindi a volte è necessario forzare il recupero successivo nel caso i dati lato server siano cambiati

L'header in questione serve a questo scopo. Può assumere i seguenti valori

• endpoint-cod: codice degli endpoint collegati separati da virgola. Ogni endpoint ha associato un codice. Passando questo parametro anche sulle get si ottiene il seguente header di response: x-cache-endpoint-cod che contiene il codice della get appena eseguita
• endpoint-url: lista degli url collegati separati da virgola

l'header della request è x-cache-relations

Esempio

----- REQUEST -----
C:\Windows\System32>curl -i -X "POST" ^
  "http://localhost:8180/it.kion.e3rest.web/api/calesa-service-v1/appelli/10143/8838/" ^
  -H "accept: application/json" ^
  -H "authorization: Basic <omissis>" ^
  -H "Content-Type: application/json" ^
  -H "X-Esse3-permit-invalid-jsessionid: true" ^
  -H "x-endpoint-relations: endpoint-cod" ^
  -d ^
"{^
  ""aaCalId"": 2020,^
  ""desApp"": ""test rest"",^
  ""tipoGestAppCod"": ""STD"",^
  ""dataInizioIscr"": ""01/01/2024"",^
  ""dataFineIscr"": ""01/03/2024"",^
  ""dataInizioApp"": ""10/03/2024""^
}"

----- RESPONSE -----
 201 Created
Server: Apache-Coyote/1.1
xRateLimitRemaining: 998
xRateLimitReset: 23
xRateLimitLimit: 60
Location: http://localhost:8180/it.kion.e3rest.web/api/calesa-service-v1/appelli/10143/8838/28
x-cache-relations: RST_CALEV1__getAppelli,RST_CALEV1__getAppelliPrenotabili
x-cache-endpoint-cod: RST_CALEV1__postAppello
Content-Length: 0
Date: Fri, 29 Mar 2024 15:53:29 GMT

----- REQUEST -----
C:\Windows\System32>curl -i -X "POST" ^
  "http://localhost:8180/it.kion.e3rest.web/api/calesa-service-v1/appelli/10143/8838/" ^
  -H "accept: application/json" ^
  -H "authorization: Basic <omissis>" ^
  -H "Content-Type: application/json" ^
  -H "X-Esse3-permit-invalid-jsessionid: true" ^
  -H "x-endpoint-relations: endpoint-url" ^
  -d ^
"{^
  ""aaCalId"": 2020,^
  ""desApp"": ""test rest"",^
  ""tipoGestAppCod"": ""STD"",^
  ""dataInizioIscr"": ""01/01/2024"",^
  ""dataFineIscr"": ""01/03/2024"",^
  ""dataInizioApp"": ""10/03/2024""^
}"


----- RESPONSE -----
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
xRateLimitRemaining: 998
xRateLimitReset: 30
xRateLimitLimit: 60
Location: http://localhost:8180/it.kion.e3rest.web/api/calesa-service-v1/appelli/10143/8838/29
x-cache-relations: http://localhost:8180/it.kion.e3rest.web/api/calesa-service-v1/appelli/10143/8838,http://localhost:8180/it.kion.e3rest.web/api/calesa-service-v1/appelli-prenotabili/10143/8838
Content-Length: 0
Date: Fri, 29 Mar 2024 15:53:58 GMT

Servizi di recupero (GET)

Servizio di paginazione

Su alcuni endpoint, dove il numero di risorse può essere elevato, è abilitato il servizio di paginazione che viene gestito dai parametri in querystring start e limit

Vengono restituiti i record partendo dal record indicato da start e per un numero di record impostato da limit

Sugli header presenti nella response è inserito il seguente header 

   "link": con gli url delle risorse collegate

il formato dell'header è definito sull' RFC-5988

ad esempio:

"link": "<https://esse3.dev-qa.cineca.it/unikion-dev1/e3rest/api/calesa-service-v1/appelli/10254/5056/?start=0&limit=50>; rel=\"first\", <https://esse3.dev-qa.cineca.it/unikion-dev1/e3rest/api/calesa-service-v1/appelli/10254/5056/?start=50&limit=50>; rel=\"next\", <https://esse3.dev-qa.cineca.it/unikion-dev1/e3rest/api/calesa-service-v1/appelli/10254/5056/?start=154&limit=50>; rel=\"last\"",

Servizio di ordinamento

L'ordinamento delle risorse, se previsto, avviene con il parametro in query order

è possibile specificare più ordinamenti separati da virgole per ordinare i risultati con criteri multipli (il primo carattere consente di specificare il criterio di ordinamento + =Ascendente, - = Discendente)

Nel caso si volessero ordinare i record con dei campi presenti su oggetti figli della classe di modello è possibile utilizzare la notazione . per indicare l'indirizzo completo del campo da utilizzare.

ESEMPIO:

[{ "cdsId": 10, 
   "adId": 10,
   "appId": 10, 
   "cdsCod": "CDS1",  
    ....
    "turni": [ { "cdsId": 10, 
                 "adId": 10, 
                 "appId": 10, 
                 "appLogId": 10,
                 "des": "descrizione libera del turno", 
                 "dataOraEsa": "10/10/2016 10:00" ,
                   ..... }],
                  "commissione": [ { "cdsId": 10, 
                                     "adId": 10, 
                                     "appId": 10, 
                                     "docenteId": 10, 
                                     .....
                                   } ] 
               } ] ,
   "sessioni": [ { "cdsId": 10, 
                   "adId": 10, 
                   "appId": 10, 
                   "aaSesId": 10,
                   "sesId": 10, 
                    ....
                  } ], 
 "commissione": [ { "cdsId": 10, 
                    "adId": 10, 
                    "appId": 10, 
                    "docenteId": 10, 
                    ....
                  } ], 
 "esameComune": [ { "cdsId": 10, 
                    "adId": 10, 
                    "aaOffId": 10, 
                    "cdsFiglioId": 10, 
                    "adFiglioId": 10, 
                    .... 
                   } ] 
}]

  order=+cdsCod,+turni.dataOraEsa

Filtro sui campi delle classi di modello

E' possibile filtrare i campi restituiti dal singolo URI tramite il parametro fields

è possibile inserire la lista dei campi da filtrare separati da virgola, come per il caso dell'ordinamento, se il campo risulta innestato in delle classi figlie occorre utilizzare la notazione con .

I filtri possibili sono quelli utilizzati nella notazione ANT GLOB PATTERNS (dalla versione 22.09.01.00)

• * seleziona un elemento del path
• ** seleziona tutti gli elementi del path
• ? seleziona un singolo carattere alfanumerico oppure - oppure _

ESEMPI

[{ "cdsId": 10, 
   "adId": 10,
   "appId": 10, 
   "cdsCod": "CDS1",  
    ....
    "turni": [ { "cdsId": 10, 
                 "adId": 10, 
                 "appId": 10, 
                 "appLogId": 10,
                 "des": "descrizione libera del turno", 
                 "dataOraEsa": "10/10/2016 10:00" ,
                 "commissione": [ { "cdsId": 10, 
                                     "adId": 10, 
                                     "appId": 10, 
                                     "docenteId": 10, 
                                     .....
                                   } ] 
               } ] ,
   "sessioni": [ { "cdsId": 10, 
                   "adId": 10, 
                   "appId": 10, 
                   "aaSesId": 10,
                   "sesId": 10, 
                    ....
                  } ], 
 "commissione": [ { "cdsId": 10, 
                    "adId": 10, 
                    "appId": 10, 
                    "docenteId": 10, 
                    ....
                  } ], 
 "esameComune": [ { "cdsId": 10, 
                    "adId": 10, 
                    "aaOffId": 10, 
                    "cdsFiglioId": 10, 
                    "adFiglioId": 10, 
                    .... 
                   } ] 
}]

• fields=cdsId,adId

  [{ "cdsId": 10, 
     "adId": 10
   }]

• fields=cdsId,turni.des

  [{ "cdsId": 10, 
     "turni": [{ des:"descrizione libera del turno" }]
   }]

• fields=cdsId,turni.**

  [{ "cdsId": 10, 
     "turni": [ { "cdsId": 10, 
                   "adId": 10, 
                   "appId": 10, 
                   "appLogId": 10,
                   "des": "descrizione libera del turno", 
                   "dataOraEsa": "10/10/2016 10:00" ,
                   "commissione": [ { "cdsId": 10, 
                                       "adId": 10, 
                                       "appId": 10, 
                                       "docenteId": 10, 
                                       .....
                                     } ] 
   }]

• fields=cdsId,turni.*

  [{ "cdsId": 10, 
     "turni": [ { "cdsId": 10, 
                   "adId": 10, 
                   "appId": 10, 
                   "appLogId": 10,
                   "des": "descrizione libera del turno", 
                   "dataOraEsa": "10/10/2016 10:00" ,
                 } ],
   }]

• fields=cdsId,**.commissione.**

  [{ "cdsId": 10, 
     "turni": [ {"commissione": [ { "cdsId": 10, 
                                       "adId": 10, 
                                       "appId": 10, 
                                       "docenteId": 10, 
                                       .....
                                     } ] 
                 } ] ,
   "commissione": [ { "cdsId": 10, 
                      "adId": 10, 
                      "appId": 10, 
                      "docenteId": 10, 
                      ....
                    } ]
  }]

Campi opzionali sulla classe di modello

Analogamente a quanto definito nel parametro fields, il parametro optionalFields consente di visualizzare i campi opzionali delle classi di modello.

Al fine di rendere più leggeri i trasferimenti dei dati sulla rete, infatti, i campi che non sono di utilizzo generale ma che sono utilizzati solo in casistiche particolari oppure come personalizzazioni specifiche non sono ritornati nelle normali response (anche se presenti nella classe di modello) per poter richiedere questi campi è necessario utilizzare il parametro indicato, i campi opzionali sono dichiarati nella documentazione sulla sezione delle classi di modello

i campi possono essere indicati specificando, come per il parametro fields, il percorso completo del campo. L'operatore * permette di selezionare tutti i campi opzionali di una sottoclasse e il valore speciale ALL consente di recuperare tutti i valori opzionali

Applicazioni di filtri predefiniti.

Normalmente i servizi esposti forniscono i dati che l'utente può visualizzare senza restrizioni applicative. Questo consente ad applicazioni di terze parti di recuperare tutti i dati di pertinenza dell'utente e di applicare eventuali filtri in autonomia, esistono alcune casistiche in cui è opportuno fornire particolari condizioni di filtro predefinite che consentono di recuperare i dati con le medesime logiche di filtro di ESSE3.

Queste condizioni, se definite sono applicabili con il parametro q sulla singola URI

Nella documentazione della URI è disponibile la lista dei filtri disponibili con la descrizione del loro funzionamento

ESEMPIO

Per il recupero delle prenotazioni studente (api/calesa-service-v1/prenotazioni/{matId}) è disponibile il parametro q=BACHECA_ESITI che filtra tra tutte le prenotazioni di un libretto solo quelle che sono visualizzate nella bacheca esiti, La lista infatti contiene tutte le prenotazioni che lo studente può visualizzare in tutti i processi (prenotazione esami, visualizzazione esiti)

Filtro sulle righe recuperate

E' possibile filtrare i record ottenuti tramite il parametro filter. In questo modo i dati vengono filtrati DOPO che è stata applicata la condizione di recupero degli stessi.
per questo motivo è preferibile utilizzare i filtri appositi degli endpoint dove presenti che consentono di effettuare un accesso dati più efficiente e ridurre i tempi di recupero

Questo servizio è pensato per filtrare i record ottenuti con dei criteri specifici che non sono definiti a sistema con un apposito parametro.

La sintassi da utilizzare utilizza il linguaggio RSQL. per la sintassi è possibile consultare la documentazione di github nel link precedente

La lista degli operatori utilizzabile è la seguente

Gestione NOT FOUND 

con la versione 19.05.02.00 la gestione dell'assenza di dati è stata modificata, precedentemente nel caso un endpoint non aveva dati da ritornare veniva utilizzato lo status code 404 (NOT FOUND) per segnalare l'assenza dei dati.

Dalla versione indicata è stato introdotto un PARAMETRO di CONFIGURAZIONE (impostabile dalla maschera "parametri di configurazione" di ESSE3

con il valore 0 TUTTE le risorse che non recuperano nessun dato non restituiranno più Http status code 404 ma 200 e il body sarà valorizzato nel seguente modo

• se la risorsa prevede un insieme verrà fornito l'insieme vuoto []
• se la risorsa prevede un oggetto verrà fornito l'oggetto vuoto {}
• se la risorsa prevede uno scalare (stringa, numero) verrà restituito null

nel caso di 1 invece si ottiene il comportamento corrente cioè Http status code 404

E' stato anche introdotto un header custom X-Esse3-Not-Found-Legacy da passare alla singola chiamata per forzare uno dei due comportamenti a prescindere dal par_conf, l'header può valere

• true: legacy mode abilitato => ottengo il 404
• false: legacy mode disabilitato => ottengo il 200

ESEMPIO

Dato il seguente servizio (che ritorna un array di oggetti) /offerta-service-va/offerte?aaOffId=2030  la risposta del sistema è la seguente

Servizi di inserimento (POST)

I servizi di post prevedono che non venga ritornato nessun valore come body nella request successiva all'inserimento, viene fornito un header specifico che punta alla risorsa appena creata

  location:<uri della risorsa appena creata>

Servizi di update (PUT)

I servizi di aggiornamento prevedono il ritorno della risorsa appena creata con i dati aggiornati