Lettura di un record

Il client richiede la lettura di un record chiamando

http(s):// www.nome-del-sito.suffisso / API / nome della tabella (sezione) / id

Per esempio, per leggere la news numero 73 sul sito test.mygelsia.it

https://test.mygelsia.it/API/news/73

A prescindere da quale sezione (tabella) del database stiate leggendo, e in quale sito, i primi campi della risposta JSON sono sempre i medesimi. Si tratta delle informazioni di servizio (metainformazioni) con cui Sar-At correda ogni record del database. Sono descritti nei precedenti capitoli di questo manuale ma, in sintesi, si tratta di:

Campo

L/S

Contenuto

id

L

Identificativo numerico univoco del record

masterId

L

Nei siti multilingue, identificativo numerico univoco della risorsa. Per esempio, se i record 1 e 2 hanno identico masterId 3 allora si tratta delle due traduzioni in due diverse lingue della medesima informazione

language

S

Codice della lingua in cui sono scritti i testi (1001: italiano; 1002: inglese; eccetera. Vedere il manuale Mantenere il sito)

creation

L

Data ed ora della prima creazione del record

authorId

L

Username del creatore del record

lastMod

S*

Data ed ora della ultima modifica del record

modifierId

S*

Username del modificatore del record

visible…

sarelHitCounter

S

Vedi precedenti capitoli di questo manuale.

saratUrl

S*

URL univoca sul sito per la consultazione dell'informazione

L: informazione accessibile sempre e solo in lettura

S: informazione modificabile attraverso l'operazione di scrittura sul record descritta qui di seguito.

S*: informazione modificabile attraverso l'operazione di scrittura sul record, ma i contenuti del campo in questo caso verrebbero autonomamente popolati da Sar-At. Per esempio, modifierId diventerebbe la username dell'utente le cui credenziali sono state usate.

Seguono tutti i campi specifici della sezione (tabella) interessata.

Nelle sezioni anagrafiche Sar-At mantiene le password in formato cifrato (vedere capitolo terzo, alla voce "sezioni a massima sicurezza"). Di conseguenza, il campo "password" apparirà sempre vuoto nel JSON che vi viene restituito.

Tenete presente che, internamente, Sar-At memorizza tutti i testi in formato HTML. Quindi nei campi di testo breve e di testo lungo che vengono restituiti dal server al client dovete aspettarvi di trovare entità SGML (come è) e tag HTML.

Nel caso di record riservato, la chiamata deve includere le credenziali. Per esempio, in un commercio elettronico businesss to business il prezzo riservato all'acquirente e il numero di scorta magazzino è probabilmente una informazione riservata ai membri registrati del gruppo "clienti". Il client deve includere, come parametri della chiamata GET:

  • username
  • password
  • group, cioè nome gruppo di appartenenza

Per esempio, per leggere la anagrafica del cliente registrato numero 15159 sul sito test.mygelsia.it, avremo:

https://test.mygelsia.it/API/registrazione/15159?username=luca@accomazzi.net&password=

tvumdb&group=registrati

Naturalmente, il caso di una anagrafica è un caso un po' particolare. Il software client che state sviluppando probabilmente non conosce lo id univoco del cliente di cui possiede le credenziali (di solito questa informazione non traspare). Per semplificare le procedure e saltare l'inutile passaggio di una ricerca per username nella base dati, Sar-At consente in questo caso di usare "ANY" al posto dell'id numerico (in modo analogo a quanto viene fatto con la procedura showForm, vedi capitolo terzo di questo manuale).

In altre parole, la URL vista qui sopra è equivalente a:

https://test.mygelsia.it/API/registrazione/ANY?username=luca@accomazzi.net&password=

tvumdb&group=registrati