API Reference Microservizi

Ogni microservizio esporrà una struttura di Modelli e di campi, e una serie di chiamate per interagire con gli stessi.

La struttura degli stessi è monodimensionale e limitata per accomodare esigenze tecniche di encoding, di funzionamento interno, di performance, e di portabilità.

il tipo di campo potrà essere uno tra:

uuid Rappresenta un descrittore

Per il campo speciale con codice “uuid” il suo schema di riferimento sarà quello descritto dal campo “model”

Per il campo speciale con codice “parent_uuid” il suo schema di riferimento sarà quello descritto dal campo “parent_model”.

Per tutti gli altri campi il suo schema di riferimento sarà quello identificato dalla proprietà “model”.

Di default lo schema di riferimento di un descrittore sarà interno al microservizio stesso, se così non fosse, occorrerà specificarlo nella proprietà “origin”, indicando nella stessa il codice o l'url del manifest del microservizio di riferimento. E' anche possibile esplicitare comunque la stessa per i campi interni con il codice o l'url del proprio manifest, o tramite la keyword “self”.

Sarà possibile valorizzare una proprietà “dependent” per indicare come l'oggetto puntato sia un oggetto figlio dell'oggetto stesso, in caso di cancellazione, la verifica di cancellabilità dovrà essere effettuata su tutti gli oggetti figlio, e, in caso di esito positivo, applicata di conseguenza. Questa funzione consentirà di avere “modelli dipendenti” e “oggetti dipendenti”, la differenza trai due scenario consente di avere “Mixed models”, dove ogni oggetto eredita la dipendenza da un padre di tipo differente (ad esempio un modello galleria o immagine applicabile a diversi modelli).

Lo stesso sarà rappresentato in JSON come una stringa contenente un uuid (RFC4122, UUID). Non sono previste prescrizioni per la rappresentazione nel repository. E' possibile assumere che sia una rappresentazione a 36 caratteri secondo lo schema esadecimale 8-4-4-4-12 (UUID Testual Representation) che rappresenti un bitfield a 128bit, in fase iniziale sarà utilizzato il formato versione 4, che potrà essere modificato in una revisione successiva per accomodare feature di domain, node, o function awareness, con cautela per mantenere retrocompabilità o per ricodificare gli identificativi generati con una versione precedente.

Non è possibile generare UUID client side.

Non è possibile generare UUID esternamente a un microservizio, ogni microservizio accoglierà come Descrittori dei propri oggetti solo quelli da lui generati, ma dovrà accogliere i descrittori generati dagli altri microservizi (per ora questa specifica non prevede alcuna verifica sulla validazione degli stessi, al di fuori della verifica generale di formato, la validazione potrà essere prevista in successive revisioni).

Le funzioni di ricerca previste per questo tipo di campo sono quelle di uguaglianza (di seguito “eq”), diversità (di seguito “neq”), esistenza (“isnotnull”) non esistenza (“isnull”), inclusione (“in”) e non API Microservizi v1.0.2 inclusione (“notin”) rispetto a un valore specificato (nessuno nel caso delle funzioni di esistenza e non esistenza) (il valore sarà un array nel caso delle funzioni di inclusione/non inclusion).

Sulle funzioni di esistenza e non esistenza potranno essere apposte delle limitazioni per ottimizzare l'indicizzazione, in questa specifica le stesse non vengono approfondite e rilasciate alle specificità delle singole implementazioni (questo, in generale, varrà per tutte le tipologie di campi).

Le funzioni di set andranno a sostituire il valore ove applicabile.

Per quanto assunto univoco è considerato un bug di sicurezza la verifica di univocità di un uuid, la sua univocità deve essere garantita solo dalla randomicità dell'algoritmo di generazione. L'unica limitazione ammissibile per evitarne la sovrapposizione è un rate limiter.

number, integer, positivenumber, positiveinteger Rappresentano un numero.

per gli stessi è possibile specificare le seguenti proprietà:

• “min”: valore minimo assumibile (default -Inf, ma default:0 se il tipo è “positiveinteger” o “positivenumber”)
• “step”: intervallo di incremento (default: 2.2204460492503130808472633361816 × 10-16 in base allo standard (ECMA-262), ma default: 1 se il tipo è “integer” o “positiveinteger”). Questo campo è obbligatorio nel caso il tipo sia “number” o “positivenumber” per consentire una corretta codifica/decodifica nel caso in cui il repository del backend non supporti l'epsilon del javascript.
• “max”: valore massimo assumibile (default +Inf)

In EcmaScript / JSON sono definiti solo numeri a virgola mobile, in json saranno rappresentati come tali Per molte applicazioni (finanziare / di sicurezza / di consistenza / di real time / di performance) non sono utilizzabili numeri a virgola mobile Sarà responsabilità del microservizio, e delle definizione dello stesso garantire una corretta conversione da e verso un certo formato quando lo stesso dovrà codificare o decodificare uno di questi campi.

Potremmo identificare un campo “prezzo” con min: 0 step: 0.01 rappresentarlo in un DBMS tramite un campo BIGINT, quindi salvando un importo tipo 45.98 come 4598, ma sarà responsabilità del microservizio fornire il valore nelle api e leggerlo dalle api come 45.98

Potremmo identificare un campo “anno” come “integer”, ma sarà cura del microservizio verificare che il dato passato in json sia un numero realmente intero

Le funzioni di ricerca previste per questo tipo di campo sono quelle di uguaglianza (“eq”), diversità (“neq”), esistenza (“isnotnull”), non esistenza (“isnull”), maggiore di (“gt”), maggiore o uguale a (“gte”), minore di (“lt”), minore o uguale a (“lte”) rispetto a un valore specificato.

In questa specifica non è previsto, ma potrà essere adottato successivamente anche una funzione di range (“between”).

Le funzioni di set andranno a sostituire il valore ove applicabile.