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.

text, longtext Rappresenta un testo, in json saranno rappresentati come stringhe

per gli stessi sarà possibile specificare le seguenti proprietà:

“min”: rappresenta la lunghezza minima (non trimmata) (default: none, il campo può essere nullable)

“max”: rappresenta la lunghezza massima (non trimmata) (default: 250 o 65535 per i campi “longtext”)

Nota bene: nel caso sia necessario supportare dei campi testo di dimensione superiore potranno essere adottate due strategie:

salvarli come blob su disco (se non si necessita di doverli ricercare)

oppure:

creare un sotto-modello che contenga dei frammenti

Questa limitazione è inserita ad-hoc nella definizione per evitare che gli oggetti possano superare una dimensione accettabile al funzionamento ottimale delle varie tecnologie di repository oggi esistenti quali: 65535 per l'InnoDB (blob esclusi, ma solo in assenza di indici, altrimenti la limitazione scende a 8126 o addirittura 767 bytes per indice (InnoDB limits)), o 16MB per MongoDB (ma in BSON, (MongoDB Limits)) o 512MB per redis (Redis String Limits) o 1 GB per memcached (ma di default 1MB: max-item size in (MemCacheD Limits)), in generale per garantire un funzionamento ottimale, performante e portabile occorrerà assicurarsi che un singolo oggetto non possa superare i 512 kB.

Questa specifica non include prescrizioni particolari per imporre questa limitazione, così come non include prescrizioni per limitare il numero dei campi per modello, che pure si consiglia di mantenere al di sotto del centinaio. In termini indicativi, per massimizzare le performance, l'ideale sarebbe quindi cercare di mantenere la dimensione di un oggetto al di sotto dei 100kB, e il numero di campi dello stesso al di sotto di una cinquantina. Conviene quindi limitare il numero di campi di tipo “longtext”.

Le funzioni di ricerca previste per questo tipo di campo sono quelle di uguaglianza (“eq”), diversità (“neq”), esistenza (“isnotnull”), non esistenza (“isnull”), inzia per (“startswith”), finisce per (“endswith”) e contiene (“contains”) rispetto a un valore specificato.

In questa specifica non sono previsti, ma potranno essere adottate successivamente anche funzioni di ricerca Full-text.

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

langtext, langlongtext Saranno equivalenti ai campi “text” e “longtext” come caratteristiche, ma da un punto di vista di comunicazione JSON richiederanno che il dato venga suddiviso per locale, quindi, invece che avere una rappresentazione “campo”:“valore” avranno una rappresentazione “campo”:{“locale”:“valore”}, le limitazioni si applicheranno al valore del singolo locale, sarà responsabilità del microservizio mapparli eventualmente su un repository monodimensionale

Le funzioni di ricerca per questo campo saranno analoghe a quelle del tipo campo “text” e “longtext” con la possibilità, nel contesto di ricerca, di poter essere applicate:

• a tutti i locale
• solo al locale corrente
• solo al locale corrente o, in assenza di un valore nello stesso, a un locale di fallback specificato

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

date, datetime, time, timerange Rappresentano unità di tempo, rappresentate in forma numerica nel seguente formato: - “datetime”: conterrà il numero di millisecondi (e non di secondi) dallo Unix Epoch (UnixEpoch) - “date”: conterrà il numero di giorni dallo Unix Epoch - “time”: conterrà il numero di millisecondi dalla mezzanotte - “timerange”: conterrà il numero di millisecondi In tutto e per tutto gli stessi saranno trattati come dei campi “integer”, non sarà possibile effettuare gli override del valore di step per i campi date Le funzioni di set andranno a sostituire il valore ove applicabile.

date, datetime, time, timerange Rappresentano unità di tempo, rappresentate in forma numerica nel seguente formato:

• “datetime”: conterrà il numero di millisecondi (e non di secondi) dallo Unix Epoch (UnixEpoch)
• “date”: conterrà il numero di giorni dallo Unix Epoch
• “time”: conterrà il numero di millisecondi dalla mezzanotte
• “timerange”: conterrà il numero di millisecondi

In tutto e per tutto gli stessi saranno trattati come dei campi “integer”, non sarà possibile effettuare gli override del valore di step per i campi date

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

boolean Rappresenterà un campo booleano.

Lo stesso in JSON sarà rappresentabile come boolean

A livello di repository è possibile implementarlo in una serie di formati (BOOLEAN; BIT, CHAR(1), TINYINT, …), ma è responsabilità del microservizio garantire la corretta conversione da/verso

l'interfaccia JSON

Le funzioni di ricerca per questo tipo di campo sono quelle di uguaglianza (“eq”), diversità (“neq”) esistenza (“isnotnull”), non esistenza (“isnull”), rispetto a un valore specificato.

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

uuid[] Rappresenta una relazione multipla tra oggetti

la stessa sarà rappresentata in json tramite un array di descrittori

la stessa sarà soggetta alla limitazione “multiuuid_max”, se fosse bisogno supportare relazioni con molteplicità superiore occorrerà prevedete un sotto-modello di transizione

la stessa sarà assunta come NON-ordinata.

Le funzioni di ricerca per questo tipo di campo saranno: contiene (“has”, considerato non a livello stringa ma a livello di contiene questo identificativo)

Le funzioni di set andranno a sostituire il valore ove applicabile. In una successiva revisione di questa specifica sarà possibile estenderle con funzioni integrative di aggiornamento differenziale.

Non sono previsti in questa specifica campi per rappresentare liste ordinate o alberi, che potranno essere descritti tramite sottomodelli di servizio in revisioni successive.

Non sono previsti campi composti in questa specifica, ma potranno esser definiti in specifiche successive tipologie di campi che estendano le verifiche sui campi già esistenti (ad esempio: un campo tipo “prezzo” può porre in automatico uno step di 2 cifre su un campo positivenumber, un campo tipo “codicefiscale” può imporre delle verifiche di congruità su un campo text e un limite di 16 caratteri)