MasonSQL - interfaccia CRUD - versione 1.6.4

Nel documento viene descritta l'interfaccia per lo scambio dei dati per le classiche operazioni di Creazione(Create), Lettura(Retrieve), Aggiornamento(Update) e Cancellazione(Delete).

L'interfaccia di comunicazione tra il client di accesso ed il server è disponibile esclusivamente con il protocollo standard HTTPS, con autenticazione basic.

Per esigenze di compatibilità con le versioni precedenti di MasonSQL e per agevolare lo sviluppo dei client di accesso sono stati utilizzati esclusivamente i metodi di accesso GET e POST.

MasonSQL GUI non utilizza l'interfaccia CRUD!
L'interfaccia CRUD è disponibile per integrare applicazioni esterne.

Su questa pagina:

Classe dell'oggetto

Nella URI viene codificata la classe dell'oggetto che si vuole leggere, modificare, ecc.

Esempi:

https://myapp.mydomain.com/dbms/campionamenti
https://myapp.mydomain.com/dbms/parametri
https://myapp.mydomain.com/dbms/formulari/siti

Nella URL (Uniform Resource Locator) della chiamata viene codificato anche il metodo richiesto e la chiave univoca dell'oggetto richiesto.

Esempi:

https://myapp.mydomain.com/dbms/campionamenti?method=update&key=12
https://myapp.mydomain.com/dbms/parametri?key=888
https://myapp.mydomain.com/dbms/parametri?method=select&key=23
https://myapp.mydomain.com/dbms/campionamenti?method=delete&key=4
https://myapp.mydomain.com/dbms/parametri?method=newkey
https://myapp.mydomain.com/dbms/parametri?method=insert&key=33
https://myapp.mydomain.com/dbms/campionamenti?method=xls

Ciascuna chiamata è di tipo atomico, o "stateless"; ovvero si conclude con una operazione completata con la risposta del server; non richiede successive interazioni.

Unica eccezione, se così si può dire impropriamente, è data dal metodo newkey che ritorna una chiave utilizzabile per l'inserimento successivo di un nuovo oggetto. Se la chiave non viene poi utilizzata per inserire un nuovo oggetto, ciò non costituisce un problema e la chiave viene scartata.

I dati degli oggetti (record delle tabelle) vengono scambiati nel formato XML con charset UTF-8.

Per compatibilità con le versioni precedenti di MasonSQL lo schema utilizzato per la risposta è il seguente:

<?xml version="1.0" encoding="utf-8"?>
<dbms method="retrieve" user="administrator" timestamp="28/04/2010 07:45:17.997114 CEST" start="0" rows="1" max_rows="1529">
      <campionamenti id="..." ... />
</dbms>

Il TAG <dbms> identifica il percorso iniziale della URI e racchiude il TAG il cui nome identifica la classe dell'oggetto (il nome della tabella è rappresentato nel formato schema.tabella con un punto come separatore).

Nel TAG <dbms> sono definiti alcuni attributi:

attributo	descrizione
method	metodo richiesto
user	corrisponde all'utente che ha effettuato la richiesta
timestamp	data di riferimento della transazione.

Attributi presenti solo con operazione retrieve:

attributo	descrizione
start	offset del primo record restituito
rows	numero di record restituiti
max_rows	numero dei record elaborati

Nella URI il nome della tabella da schema.tabella viene codificato con schema/tabella. In mancanza di indicazione dello schema si intende che la tabella è presente nello schema di default definito nel file di configurazione Apache DefaultSchema (Default: public).

ATTENZIONE: Nelle operazioni di modifica ed inserimento è obbligatorio utilizzare il TAG corrispondente all'oggetto identificato nella URI.

I campi della tabella vengono rappresentati nello schema XML utilizzando parametri del TAG.

Esempio:

<?xml version="1.0" encoding="utf-8"?>
<dbms method="retrieve" user="administrator" timestamp="28/04/2010 07:48:19.200846 CEST" start="0" rows="1" max_rows="1">
      <campionamenti stato_rapporto="firmato" data_ingresso="01/01/2010" persona_prelievo="1135"
          persona_responsabile3="" id_laboratorio="12" data_inizio_prova="01/01/2010"
          persona_responsabile2="" stato="Completato" durata_prelievo="" id="1136"
          id_tipi_campionamenti="514" osservazioni="" persona_responsabile="41" id_sito="41"
          data_fine_prova="09/10/2000" codice="[555444/03]" ora_prelievo="11:40"
          data_prelievo="03/10/2000" id_rapporto="1114"/>
</dbms>

I parametri (campi della tabella) contenenti caratteri riservati e/o proibiti devono essere codificati:

Caratteri riservati e/o proibiti	Caratteri codificati
<	&lt;
&	&amp;
<CR>	\n
...	...

attributo father_key

Nel caso in cui il metodo richiede l'attributo father_key e la tabella non ha un valore di padre, deve essere usato il valore speciale -2 che inibisce il controllo della presenza del padre.
Una tabella ha un padre quando esiste il metodo FATHER nel suo file .sql.

Autenticazione

L'interfaccia è accessibile con autenticazione basic (password protetta dal canale cifrato SSL del protocollo HTTPS). L'utente che accede eredita i diritti in base ai gruppi di appartenenza, così come gestiti nelle applicazioni. Se l'utente appartiene ad un determinato gruppo avrà diritto di accedere agli oggetti inerenti quel gruppo, così come accade attraverso l'interfaccia nel browser.

Permessi di accesso

La tabella di autorizzazioni dell'utente è disponibile tramite interfaccia web dal menu Autorizzazioni->Funzioni e autorizzazioni.
La tabella associa le autorizzazioni consentite (Dbms, Select, Update, Insert, Delete, Log, Menu, Stampa, PrintSel, XLS) ai gruppi.
Per poter utilizzare l'interfaccia CRUD per l'accesso a un determinato oggetto/tabella l'utente deve appartenere a un gruppo con autorizzazione Dbms.
L'accesso ai metodi e alle classi degli oggetti/tabelle dall'interfaccia CRUD è controllato dall'autorizzazione Dbms e dalle autorizzazioni Select, Update, Insert, Delete per l'accesso ai dati.
Tramite il metodo info è possibile verificare le autorizzazioni concesse sugli oggetti/tabelle.

Attenzione prima di disattivare eventuali autorizzazioni per la Funzioni record perché rischiate di impedire a voi stessi l'accesso alla tabella delle autorizzazioni dal menu Autorizzazion->Funzioni e autorizzazioni.

I metodi di classe e gli attributi

Nome chiave

Le classi di oggetti (le tabelle) utilizzano come chiave univoca un campo che non ha un nome univoco ma può cambiare in ciascuna tabella, anche se è comunque un parametro di progetto e quindi non cambia nel tempo. Il nome di default è id, ma per esser certi è possibile reperire il nome della chiave univoca utilizzata nell'oggetto utilizzando il metodo keyname:

Esempio:

https://myapp.mydomain.com/dbms/campionamenti?method=keyname

Verrà restituito il seguente documento XML contenente il nome del campo chiave:

Codice: 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<dbms method="keyname" user="admin" timestamp="28/04/2010 12:03:10" >
      <campionamenti keyname="id" />
</dbms>

In caso di errore il server risponderà con errore (400) accompagnato da un documento contenente il messaggio dell'errore.

Info

Con il metodo info viene restituito un documento XML contenente una serie di informazioni utili sull'oggetto.

Esempio:

https://myapp.mydomain.com/dbms/campionamenti?method=info

Verrà restituito il seguente documento XML:

Codice: 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<dbms method="info" user="admin" timestamp="28/04/2010 12:00:00" >
      <campionamenti keyname="id" log="0" delete="1" print="1" insert="1" dbms="1" xls="1" 
                  printsel="1" update="1" select="1" father_name="" father_id_name="" father_key_name="" >
            <field size="4" name="id" type="integer" descr="" primary_key="1" notnull="1" />
            <field size="4" name="id_sito" type="integer" descr="Sito prelievo" notnull="1" />
            <field size="4" name="data_prelievo" type="date" descr="Data di prelievo" />
            ......
            <field size="500" name="osservazioni" type="character" descr="Osservazioni" />
            <child field="id" table="parametri" key="id_campione" />
            <relation field="persona_responsabile" table="anagrafiche" />
            <relation field="id_sito" table="siti" />
            ......
            <relation field="cod_campionamenti" table="cod_campionamenti" key="codice" />
      </campionamenti>
</dbms>

• <field/> identifica le caratteristiche di un attributo,
• <child/> identifica la relazione con un oggetto figlio (relazione n:1),
• <relation/> identifica la relazione con un diverso oggetto (relazione 1:n)

Attenzione che <child/> e <relation/> compaiono se nella dichiarazione degli oggetti vengono descritte le rispettive relazioni (metodi ENTITY_CHILDREN e ENTITY_RELATIONS).

Numero di record presenti

Con il metodo numrec viene restituito un documento XML contenente la quantità di record presente in archivio che l'utente può recuperare.

Esempio:

https://myapp.mydomain.com/dbms/campionamenti?method=numrec

Metodo della chiamata: GET

parametro	valore	descrizione
father_key	FFFF	chiave univoca del padre (obbligatoria se l'oggetto ha un padre)

Esempio:

Codice: 200 OK
Content-Type: text/xml; charset=utf-8

<dbms method="numrec" user="admin" timestamp="28/04/2010 12:00:00" >
    <campionamenti numrec="1780" />
</dbms>

Lettura

La URL per effettuare una operazione di lettura di un oggetto è costruita nel modo seguente:

https://myapp.mydomain.com/dbms/parametri?method=retrieve&key=NNNN

oppure

https://myapp.mydomain.com/dbms/parametri?method=retrieve&father_key=NNNN

È possibile inoltre ricercare più oggetti con il parametro where con una query SQL limitata. Nell'esempio di utilizza la clausola like:

https://myapp.mydomain.com/dbms/parametri?method=retrieve&rows=10&where=campione like 'mycode%'

ATTENZIONE: Nell'esempio i caratteri come ad esempio lo spazio nella URL vanno convertiti (lo spazio viene convertito con %20). Per maggior chiarezza questi caratteri vengono mostrati nell'esempio senza conversione, anche perché alcuni browser ne permettono l'utilizzo in quanto effettuano la conversione prima della trasmissione al server.

Metodo della chiamata: GET

parametro	valore	descrizione
key	NNNN	chiave univoca dell'oggetto da recuperare (generalmente è un numero naturale)
father_key	FFFF	chiave univoca del "padre"
rows	RRR	numero di righe da restituire (valore predefinito impostato con Apache DefaultRetrieveRows [100]; valore massimo limitato a MaxRetrieveRows [65536])
start	SSS	posizione da cui mostrare i dati (0 corrisponde alla prima riga)
where	codice=XXX	query SQL di ricerca limitata agli operatori di confronto =, =, <, >, <=, >=, like, *~ e l'operatore and

Esempi:

https://myapp.mydomain.com/dbms/parametri?key=888
https://myapp.mydomain.com/dbms/parametri?method=retrieve&key=23
https://myapp.mydomain.com/dbms/parametri?method=retrieve&father_key=700
https://myapp.mydomain.com/dbms/parametri?method=retrieve&father_key=700&where=cod_campionamenti='biogas'

La risposta del server sarà un documento XML contenente il record richiesto (con parametro key) o i record collegati all'oggetto padre oppure il risultato della query di ricerca.

Esempio:

Codice: 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<dbms method="retrieve" user="admin" timestamp="28/04/2010 12:00:00" start="0" rows="2" max_rows="1801">
        <parametri parametro="Quantità media dei liquami" risultato="22" id_campione="11111" ord="0" 
                   id_metodo="321" um="mc/h" cod_parametri="Qmedia" incertezza="" tipo="N" metodo="Portata" 
                   parametro_metodo="" id="24335" sinal="0" valore="20" />
        <parametri parametro="Coefficente Rip. Portata" risultato="0.17" id_campione="11111" ord="1"
                   id_metodo="313" um="." cod_parametri="coeff_ripp" incertezza="" tipo="K" metodo="CoeffRPot"
                   parametro_metodo="" id="243334" valore="0.2225" />
</dbms>

In caso di errore il server risponderà con errore (400) accompagnato da un documento contenente il messaggio dell'errore.
La chiave del padre è obbligatoria se è dichiarato il padre.
Per accedere ad un intero set di record di grande dimensione, maggiore del limite imposto (rows=MaxRetrieveRows [65536 record]) utilizzare il parametro start con più chiamate.
Per recuperare gli ultimi record del recordset, utilizzare il metodo numrec per conoscere il numero di record presenti e poi eseguire un metodo retrieve con start = numrec - rows.

Lettura con risposta nel formato Json

Per effettuare una operazione di lettura con risposta nel formato JSON di un oggetto aggiungere il parametro "envelope_response=rest" alla URL; ad esempio:

Esempio:

https://myapp.mydomain.com/dbms/parametri?method=retrieve&key=999&envelope_response=rest

La risposta del server sarà un documento JSON contenente il record richiesto:

Codice: 200 OK
Content-Type: application/json; charset=utf-8
Content-Range: items 0-29/30

 [
{"nome":"Admins","commento":"Utenti amministratori","descrizione":"Amministratori","id":1},
...   
]

Nuova chiave

È possibile inserire un nuovo oggetto sia fornendo la chiave univoca oppure non fornendo la chiave univoca. Nel primo caso è possibile reperire una chiave univoca utilizzabile effettuando una chiamata (GET) con URI la classe dell'oggetto (la tabella) e con metodo newkey.

Esempio:

https://myapp.mydomain.com/dbms/campionamenti?method=newkey

Verrà restituito il seguente documento XML contenente il codice univoco utilizzabile per inserire un nuovo documento:

Codice: 200 OK
Content-Type: text/xml; charset=utf-8

    <?xml version="1.0" encoding="utf-8"?>
    <dbms method="newkey" user="admin" timestamp="28/04/2010 12:00:00" >
        <campionamenti key="1136" keyname="id" />
</dbms>

In caso di errore il server risponderà con errore (400) accompagnato da un documento contenente il messaggio dell'errore.

Creazione

La URL per effettuare l'operazione di inserimento di un nuovo oggetto è costruita nel modo seguente:

https://myapp.mydomain.com/dbms/campionamenti?method=create&key=NNNN&father_key=FFFF

Metodo della chiamata: POST

parametro	valore	descrizione
key	NNNN	chiave univoca del nuovo oggetto (parametro opzionale)
father_key	FFFF	chiave univoca dell'oggetto "padre" (parametro opzionale)

Esempi:

https://myapp.mydomain.com/dbms/campionamenti?method=create&key=1136
https://myapp.mydomain.com/dbms/parametri?method=create&key=1137&father_key=12
https://myapp.mydomain.com/dbms/parametri?method=create&father_key=120

<dbms>
  <campionamenti stato_rapporto="firmato" persona_prelievo="134" 
   id_tipi_campionamenti="491" osservazioni="" persona_responsabile="241" id_sito="101" />
</dbms>

Nel caso non venga fornita la chiave univoca il server inserirà un nuovo record attribuendo una chiave univoca reperibile nel documento contenente il record creato.
I campi non forniti resteranno vuoti oppure inizializzati con i valori di "default" se previsti.

ATTENZIONE: Si sconsiglia di effettuare creazioni senza la chiave univoca in quanto in caso di problemi nella comunicazione c'è il rischio di inserire più record uguali, oppure di non conoscere la chiave del record appena inserito.

La risposta del server sarà un documento XML contenente il record generato:

Codice: 200 OK
Content-Type: text/xml; charset=utf-8

      <?xml version="1.0" encoding="utf-8"?>
      <dbms method="create" user="admin" timestamp="28/04/2010 12:00:00" >
           <campionamenti stato_rapporto="firmato" ... id="1136" />
</dbms>

In caso di errore il server risponderà con errore (400) accompagnato da un documento contenente il messaggio dell'errore.

Modifica

La URL per effettuare una operazione di modifica di un oggetto è costruita nel modo seguente:

https://myapp.mydomain.com/dbms/parametri?method=update&key=NNNN

Metodo della chiamata: POST

parametro	valore	descrizione
key	NNNN	chiave univoca dell'oggetto da recuperare (generalmente è un numero naturale)

Esempio:

https://myapp.mydomain.com/dbms/campionamenti?method=update&key=123

<?xml version="1.0" encoding="utf-8"?>
<dbms>
        <campionamenti stato_rapporto="firmato" ... id="123" />
</dbms>

I campi non forniti non verranno modificati.

La risposta del server sarà un documento XML contenente il record modificato:

Codice: 200 OK
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="utf-8"?>
<dbms method="update" user="admin" timestamp="28/04/2010 12:00:00" >
        <campionamenti data_ingresso="02/03/2010" codice="AX400/2" id="123"
         osservazioni="Commento\nsu\npiù\nrighe" />
</dbms>

In caso di errore il server risponderà con errore (400) accompagnato da un documento contenente il messaggio dell'errore.

Cancellazione

La URL per effettuare una operazione di cancellazione di un oggetto è costruita nel modo seguente:

https://myapp.mydomain.com/dbms/parametri?method=delete&key=NNNN

Metodo della chiamata: GET

parametro	valore	descrizione
key	NNNN	chiave univoca dell'oggetto da cancellare (generalmente è un numero naturale)

Esempio:

https://myapp.mydomain.com/dbms/parametri?method=delete&key=23

<?xml version="1.0" encoding="utf-8"?>
<dbms method="delete" user="admin" timestamp="28/04/2010 12:00:00" >
        <parametri id="23" />
</dbms>

La risposta del server sarà OK (200) con invio di un documento XML contenente i record cancellati, oppure errore (400) accompagnato da un documento contenente il messaggio dell'errore.

Nel caso si faccia riferimento a record inesistenti o non accessibili dall'utente autenticato essi non verranno riportati nel documento XML di risposta.

Xls

La URL per effettuare il download di un file nel formato XLS contenente i record selezionati è costruita nel modo seguente:

https://myapp.mydomain.com/dbms/parametri?method=xls

Metodo della chiamata: GET

parametro	valore	descrizione
where	codice=XXX	query di ricerca limitata agli operatori di confronto =, =, <, >, <=, >=, like, *~ e l'operatore and
start	SSS	posizione da cui mostrare i dati (0 corrisponde alla prima riga)
rows	RRR	numero di righe di record da ritornare (quando non si utilizza il parametro 'key', limitato a MaxRetrieveRows [65536])
key	NNNN	chiave univoca dell'oggetto da recuperare (generalmente è un numero naturale)
father_key	FFFF	chiave univoca del "padre"

Messaggi di errore

In caso di errore nella richiesta, violazione dei diritti o nella risposta del database il messaggio di errore viene inviato al client con errore 400 Bad Request ed un documento XML contenente l'errore e, se abilitato il livello di debug, anche lo stack-trace dell'errore nel codice:

<error user="administrator" timestamp="28/04/2010 13:10:22.434 CEST" >
   <message>No access to record or record not exists</message>
   <debug row="1">
    Stack: [/opt/masonsql/htdocs/lib/my_library.comp:300], [/usr/local/share/perl ...n.comp:1112]\n
   </debug>
</error>

Di seguito alcuni messaggi di errore, tra i più significativi:

Messaggio	Descrizione
No Dbms permission	L'utente non ha diritto di accesso alla funzionalità
No insert permission	L'utente non ha diritto di inserire nuovi oggetti
No delete permission	L'utente non ha diritto di cancellare oggetti
No update permission	L'utente non ha diritto di modificare oggetti
Unespected father_key value	Valore inaspettato del parametro father_key (0 oppure <= -2)
No father retrieve permission	L'utente non ha diritto di leggere il padre
No related ObjectName retrieve permission	L'utente non ha diritto di leggere l'oggetto collegato ObjectName
No father record retrieve	L'utente non ha diritto di leggere lo specifico oggetto padre
No related ObjectName record retrieve	L'utente non ha diritto di leggere lo specifico oggetto collegato ObjectName
No key param	Manca nella richiesta il parametro 'key'
No multiple key in param key	È stato fornito un elenco di chiavi nella richiesta
No record retrieve or record not exists	L'oggetto fornito non esiste o non si hanno sufficienti diritti di accesso all'oggetto
Delete record return N rows	La cancellazione dell'oggetto ha restituito un numero di oggetti diverso da uno
Father is not defined from ...	Il padre non è definito; il parametro father_key è inaspettato
No Father id/key param with father ...	Manca il parametro father_key relativo all'oggetto PADRE
No Father id/key == -1	La chiave di valore "-1" è riservata dal framework e se utilizzata genera errore
No key == -1	La chiave di valore "-1" è riservata dal framework e se utilizzata genera errore
Defined Father id/key param without father definition	Fornito il parametro father_id nella chiamata di un oggetto senza padre
Key already used	In inserimento, la chiave fornita è già utilizzata (non è detto che l'utente abbia comunque accesso a quell'oggetto)
Key greater last key	In inserimento, la chiave fornita è maggiore dell'ultima chiave generata
No content	Chiamata POST senza contenuto
Malformed xml content: no tag	Il documento trasmesso non contiene il blocco XML: ....

Errori segnalati relativi al campo where, utilizzabile con il metodo retrieve:

• Utilizzo della parola riservata '***' non autorizzata
• Utilizzo dell'operatore '***' non autorizzato
• Utilizzo del campo '***' non autorizzato
• Utilizzo della funzione '***' non autorizzata
• Errore di sintassi: termine '***' sconosciuto
• Errore di sintassi: manca un delimitatore di stringa
• Errore di sintassi: mancante/i N parentesi di chiusura
• Errore di sintassi: parentesi di chiusura senza la corrispondente parentesi di apertura

Test & debug

Per valutare il comportamento dell'interfaccia è possibile utilizzare la pagina html:

https://myapp.mydomain.com/test/test_crud.html

È possibile indicare lo schema, tabella, chiave ed il documento XML (per update e insert) nonché il formato JSON/XML (solo retreive) su cui eseguire le operazioni di: info, numrec, newkey, update, insert, e delete. Viene restituito il record di risposta nel riquadro sottostante.