API Rest OpenAPI > Utilizzo client delle API REST

Obiettivo del client generato a partire dallo swagger personalizzato per modelli è quello di supportare l’integratore nello sviluppo del codice. Quest’ultimo pur non conoscendo i dettagli dei modelli creati dal disegnatore delle soluzioni in Jamio, avrà nel client la definizione corretta delle classi che rappresentano tali modelli. Difatti, è stato adoperato un meccanismo di naming che consente la gestione delle logiche di coordinamento tra gli aspetti di design time che incidono sulla definizione del modello e sulle procedure di deserializzazione nel client. Tale meccanismo si poggia sul concetto di impronta del modello personalizzato.

Tuttavia, questo non implica per l’integratore la non conoscenza di alcune informazioni essenziali per poter consentire il corretto funzionamento del client quali:

1.il repository detto anche identificativo dell'area destinatario dell’integrazione. Sebbene il client costruito possa essere reso indipendente dallo specifico repository su un piano progettuale, in fase di esecuzione lo specifico client deve poter essere “configurato” per operare sullo specifico repository. Il repositoryID è reperibile accedendo alla console di amministrazione https://paas.jamio.com/adminconsole;

2.la modelurl dei modelli. Tale informazione è reperibile accedendo alla console di amministrazione, nella riga di dettaglio dei singoli modelli o selezionando uno o più modelli di riferimento, facendo clic su Info modelli.

Pertanto, la loro conoscenza è fondamentale per poter effettuare le chiamate REST tramite i metodi definiti nelle classi rappresentative dei controller.

Nello sviluppo del proprio progetto, l’integratore deve:

•implementare le funzionalità specifiche del progetto, potendo disporre della definizione autogenerata nel client e che riflette la modellazione effettuata dal progettista del Jamioware;

•utilizzare le classi dei controller agganciandoli agli oggetti rappresentati con le classi di modellazione, integrando le informazioni di Modelurl e RepositoyID.

Infine l’integratore, nella costruzione del client, deve tener conto della gerarchia impostata tra le classi definite nel namespace di Model.

Gerarchia delle classi nel client

Le diverse classi generate nel client sono riconducibili ai servizi che in piattaforma gestiscono la specifica risorsa. Una risorsa generica non personalizzata e gestita da un determinato servizio è rappresentata da una specifica classe da cui, con l’ereditarietà, è possibile definire le classi specifiche rispettando la seguente gerarchia:

•Classe che rappresenta la risorsa generica per uno specifico servizio della piattaforma (es. “Data” per le risorse gestite dal servizio di DataManagement). Tale classe contiene tutte le proprietà specifiche di una risorsa Data non personalizzata, eccezion fatta per la proprietà Fields che riflettendo la personalizzazione effettuata dal progettista è demandata in una classe specifica. Tra le proprietà di questa classe, la StructureHash di tipo string riflette il concetto di impronta della versione del modello.

•Classe che rappresenta l’interfaccia comune a tutte le versioni del modello utilizzato per la personalizzazione in Jamio (es. “Ordine” Tra le informazioni disponibili, nel client viene precisata la Structure Hash del modello più recente, nonché il riferimento temporale della registrazione del modello).

•Classe che rappresenta una specifica versione di un modello (es. “Ordine163BBC388” con “163BBC388” che rappresenta il valore della Structure Hash della versione del modello rappresentato in quella classe; nel client viene precisata tale structure Hash e il riferimento temporale della registrazione). All’interno della Classe vi è una proprietà descritta da un’ulteriore classe rappresentativa della personalizzazione della risorsa (Fields).

•Classe che rappresenta la personalizzazione della risorsa (es. “Ordine163BBC388Fields” che caratterizza la personalizzazione del modello della risorsa in Jamio).

Ciclo di vita delle risorse e relazioni con le definizioni del modello

Per poter gestire il ciclo di vita delle risorse è necessario conoscere l’URL del modello. In fase di creazione, non è necessario conoscere la versione specifica poiché la risorsa verrà creata utilizzando sempre l’ultima versione del modello registrato. Pertanto in fase di creazione è sufficiente conoscere il solo URL del modello pubblicato nella forma seguente.

“ID repository di pubblicazione”/Model/”ID Modello nel repository di pubblicazione”

Per poter, invece, gestire una risorsa è necessario conoscere anche la versione del modello registrato, come meglio precisato nella forma seguente.

“ID repository di pubblicazione”/Model/”ID Modello nel repository di pubblicazione/versione del Modello Registrato”

Gli elementi che incidono nella definizione di una versione, possono essere di molteplice natura:

•tipologia di elementi della struttura dati

•nome degli elementi della struttura dati

•elementi di layout

•regole di comportamento

•definizione di alias

•risoluzione di alias

•…

L’eliminazione di un modello pubblicato non incide sull’utilizzo a runtime del modello stesso.

Sebbene per creare una risorsa è necessario specificare l’URL del modello pubblicato, qualora esso venga eliminato, si permette comunque la creazione di quel modello in quanto l’URL serve per indirizzare implicitamente un modello registrato nella sua ultima versione oppure ad una versione specifica qualora essa venga indicata.

La versione del modello registrato e l’URL del modello pubblicato sono proprietà della risorsa.

I concetti di pubblicazione, registrazione e versionamento sono specifici delle logiche della piattaforma di Jamio openwork e sottintendono ad ottimizzazioni di logiche interne alla piattaforma.

I client delle API REST non devono essere dipendenti dal repository e non devono riflettere nel versionamento gli aspetti di modellazione che sono di governo esclusivo della piattaforma quali la risoluzione di alias, definizione di layout, regole di comportamento. Ne consegue che per abilitare la costruzione di client invarianti rispetto al repository di registrazione, è necessario che essi siano informati esclusivamente sulle variazioni di design della struttura dati (nome, tipo e cardinalità degli elementi della struttura dati.