Differenze

Queste sono le differenze tra la revisione selezionata e la versione attuale della pagina.

--- apireference:struttura [2024/04/08 10:07] – marcomerlino
+++ apireference:struttura [2024/04/08 10:41] (versione attuale) – marcomerlino
@@ Linea 48: / Linea 48: @@
   * "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)
+=== Note importanti: ===
+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.
+=== Ad esempio: ===
+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.
+=== Note aggiuntive sui tipi di campo ===
+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)

API Reference Microservizi

Strumenti Utente

Strumenti Sito

Differenze

Strumenti Pagina