API Reference Microservizi

Di seguito esemplificheremo le api di base

Questa api consentirà di richiedere al backend la generazione di un determinato numero di oggetti di un determinato modello (fino a un massimo di “create_max”). Gli oggetti saranno tutti creati in stato “GENERATO” con i parametri di base descritti nella sezione sul LifeCycle.

Da un punto di vista di Access Control questa api NON necessita di verifiche (chiunque, anche senza token può richiedere delle generazioni, sarà oggetto di analisi future lo studio di eventuali rate-limiter).

La risposta potrà essere:

• un array di oggetti generati
• un oggetto di errore

Esempio di definizione:

“new”:{“name”:“Create new objects”,“method”:“GET”,“url”:“/api/product/create/”,“params”:[{“code”:“num”,“name”:“Numero”,“type”:“positiveinteger”,“required”:true}],“response”:“array”,“capabilities”:{}}

Esempio d’uso:

curl -s https://pim.neosidea.com/api/product/create/2

{

 "result":[
    {
       "uuid":"7020f592-20f5-48dd-9295-481b3ffb3c87",
       "created":1710164142000,
    },
    {
       "uuid":"5ca2e6ea-fde4-4b08-aad8-56addee6dafa",
       "created":1710164142001,
    }
 ]

}

Questa api consentirà di aggiornare degli oggetti, è possibile passare un array di oggetti (anche solo parziali, procedendo ad applicare i cambi) (fino a un massimo di save_max oggetti), e provvederà ad effettuare le verifiche di consistenza, congruità, se applicabili.

La risposta potrà essere:

• un esito positivo (json “true”)
• un oggetto di errore

Non è incluso in questa api (ma lo sarà successivamente) la possibilità che la stessa ritorni uno o più job id.

E' possibile passare a questa interfaccia oggetti privi di Identificativo (che quindi non sono passati nello stato “GENERATO”), questo può essere utile per tutta una serie di scenari di salvataggi massivi, o di semplificazione/caricamento dati, in quel caso, se sarà valorizzato il campo committed il backend sarà responsabile di generarli, applicare i valori, e salvarli, ciònonostante in quello scenario il backend non è tenuto (e nella specifica corrente non prevede) a ritornare gli identificativi generati (un esempio d'uso di questa funzione può essere un api per salvare dei log). Se invece il campo committed non fosse valorizzato verrà ritornato un errore come controllo di sicurezza. Da un punto di vista di Access Control questa api può richiedere (ma non necessariamente, può anche essere aperta a tutti, compresi client senza token) almeno una delle seguenti capabilities:

• cap_MODEL_create
• cap_MODEL_create_own
• cap_MODEL_edit
• cap_MODEL_edit_own
• cap_MODEL_delete
• cap_MODEL_delete_own

a seconda che stia committando, aggiornando, o cancellando un elemento.

La differenza tra le capabilities di base e quelle own sta su una verifica dell'owner dell'oggetto e, quindi:

cap_MODEL_edit consentirà di modificare tutti gli oggetti cap_MODEL_edit_own consentirà di modificare solo gli oggetti il cui owner sia l'attore corrente MODEL nell'esempio sta ad indicare l'obbiettivo della capability e non il particolare modello, nel caso di modelli non-first class, il backend potrebbe verificare la capability di un oggetto padre. La presente specifica si limita ad enunciare e descrivere la granularità delle capabilities a livello utente, sarà compito delle successive release andare a dettagliare un uso più granulare delle stesse, tipo la possibilità di assegnare delle capability e ownership di gruppo singole e/o multiple e gestire l'unione e l'intersezione delle stesse. Non ci sono garanzie di transazionalità sull'interezza della transazione, solo una bassa probabilità di inconsistenza sul singolo oggetto. Nel caso in cui l'operazione fallisca durante un passaggio a metà salvataggio, solo una parte degli oggetti sarà stata salvata ma senza ulteriori dettagli.

Esempio di definizione:

“save”:{“name”:“Save objects”,“method”:“POST”,“url”:“/api/product/save/”,“params”:[],“data”:“array”,“response”:“boolean”,“capabilities”:{“commit” [“cap_MODEL_create”,“cap_MODEL_create_own”],“edit”:[“cap_MODEL_edit”,“cap_MODEL_edit_own”],“delete”:[“cap_MODEL_delete”,“cap_MODEL_delete_own”]}}

Esempio d’uso:

curl -s -X POST -H “Content-Type: application/json” https://pim.neosidea.com/api/product/save/ -d

[

 {
    "uuid":"7020f592-20f5-48dd-9295-481b3ffb3c87",
    "created":1710164142000,
    "name":"Nuovo prodotto"
    "committed":1
 },

]

Risposta:

{“result”:true}

Questa api consente di caricare il contenuto di alcuni oggetti di un determinato modello (Attenzione: allo stato attuale la stessa non è multi-modello, il fatto di renderla tale potrebbe essere un'estensione successiva/un compito di un aggregatore e non è incluso nella presente specifica).

La risposta potrà essere:

• un array di oggetti
• un oggetto di errore

Da un punto di vista di Access Control questa api NON necessita di verifiche (chiunque, anche senza token può richiedere il caricamento di oggetti, sarà oggetto di analisi future lo studio di eventuali rate-limiter, da un punto di vista di sicurezza i campi “sensibili” devono essere marcati come “hidden”, e sarà possibile accederci con chiamate custom, e la possibilità di scansione è mitigata unicamente dalla dimensione dello spazio di generazione degli identificativo).

Esempio di definizione:

“load”:{“name”:“Load objects”,“method”:“POST”,“url”:“/api/product/load/”,“params”:[],“data”:“array”,“response”:“array”,“capabilities”:{}}

Esempio d’uso:

curl -s -X POST -H “Content-Type: application/json” https://pim.neosidea.com/api/product/load/ -d ‘[“5ca2e6ea-fde4-4b08-aad8-56addee6dafa”,“91f177cf-1e2d-48fd-be4c-76c1835acab8”,“5c4bdd3c92fc-4f36-92bc-ae571597843b”]’

Risposta: {

 "result":[
    {
       "uuid":"7020f592-20f5-48dd-9295-481b3ffb3c87",
       "created":1710164142000,
       "name":"Nuovo prodotto 1",
       "committed":1710164142001
    },
    {
       "uuid":91f177cf-1e2d-48fd-be4c-76c1835acab8",
       "created":1710164142000,
       "name":"Nuovo prodotto 2",
       "committed":1710164142001
    },
    {
       "uuid":"5c4bdd3c-92fc-4f36-92bc-ae571597843b",
       "created":1710164142000,
       "name":"Nuovo prodotto 3",
       "committed":1710164142001
    },
 ] 

}

Questa api consentirà di ricercare oggetti di un determinato tipo, Saranno ricercabili solo gli oggetti in stato “ATTIVO”, sarà possibile porre dei filtri, delle limitazioni e delle proiezioni sul risultato come di seguito descritto. Da un punto di vista di Access Control questa api potrà richiedere una capability tipo cap_MODEL_search, cap_MODEL_search_own simile a quelle descritte per il salvataggio (ma non è richiesto).

La stessa accetta i seguenti parametri:

query: un campo testuale per effettuare una ricerca su tutti i campi testuali ricercabili a seconda del contesto filter: una struttura di espressioni di ricerca sort: un oggetto contenente un campo “field” (stringa, codice di campo) e un campo “desc” (boolean) offset: un numero intero limit: un numero intero, limitato da “search_max” format: una stringa, definisce l'output scope e può essere:

• undefined o “default”: viene ritornato tutto l'oggetto;
• “related”: viene ritornato tutto l'oggetto, e viene ritornato un oggetto contenente gli oggetti relazionati organizzati per modello (in maniera opportunistica e
• implementation-dependent, senza alcuna garanzia, alcuni microservizi potrebbero rifiutarsi di implementarlo, o implementarlo sulla base dell'origin della relazione)
• “count”: ritorna solo il numero dei risultati
• “autocomplete”: ritorna solo i campi “uuid” e “memo”, imposta come contesto di ricerca libera i soli campi marcati per l'autocomplete
• “ui”: ritorna tutti i campi di tipo “uuid” e “uuid[]” (ad eccezione del campo con codice “uuid” del modello master della ricerca) sostituiti con la rispettiva stringa

mnemonica inputformat: una string, definisce il comportamento del parser della query di ricerca, e può essere:

• undefined o “default”: la query di ricerca viene parserizzata normalmente
• “ui”: tutti i campi di tipo “uuid” o “uuid[]” useranno la funzione “contains” e conterranno una ricerca testuale da applicare sul modello relativo

E' possibile estendere i format qui specificati con format specifici per microservizio, in tal senso viene riservata una nomenclatura per il formato come: “codicemicroservizio_codicemodello_implementationdependant”.

Per quanto riguarda l'autocomplete è ammissibile che lo stesso, allo scopo di valutare la stringa di ricerca ignori i campi marcati come “autocomplete” e si limiti a:

• saper riconoscere e ricercare un uuid
• saper ricercare la stringa di ricerca nel campo memo in startswith e/o in contain

questa eventuale limitazione è giustificabile per singolo modello di microservizio allo scopo di privilegiare le performance rispetto all'accuratezza.

Il formato di autocomplete dovrà utilizzare i filtri e il limit ma ignorerà il campo offset e l'ordinamento. L'offset sarà sempre 0, l'ordinamento a tendere sarà dato dal peso del risultato nella ricerca full-text e per ora sarà dipendente dall'implementazione.

La risposta potrà essere:

• un array di oggetti
• un numero
• un oggetto di errore

Esempio di definizione:

“search”:{“name”:“Search objects”,“method”:“POST”,“url”:“/api/product/search/”,“params”:[],“data”:“object”,“response”:“array”,“capabilities”:{“search” [“cap_MODEL_search”,“cap_MODEL_search_own”]}}

Esempio d’uso:

curl -s -X POST -H “Content-Type: application/json” https://pim.neosidea.com/api/product/search/ {

 "query":"Vino Barricato",
 "filter":{
    "func":"and",
    "fields":[
       {
          "func":"or",
          "fields":[
       {
          "func":"eq",
          "field":"brand",
          "value":"1fedee56-4841-4a17-b867-b339849c9b37",
       },
    {
       "func":"startswith",
       "field":"name",
       "value":"Barolo"
    },]
 },
 {
    "field":"year",
    "func":"gt",
    "value":2016
 }]
 },
    "format":"related",
    "sort":{
       "field":"publishrequest",
       "desc":true
    },
 "offset":0,
 "limit":10

}

Risposta:

{

 "result":[
    {
       "uuid":"7020f592-20f5-48dd-9295-481b3ffb3c87",
       "created":1710164142000,
       "name":"Nuovo prodotto 1"
       "committed":1710164142001
    },
 {
    "uuid":91f177cf-1e2d-48fd-be4c-76c1835acab8",
    "created":1710164142000,
    "name":"Nuovo prodotto 2"
    "committed":1710164142001
 },],
 "related":{
    "brand":[
       {
          "uuid":"7020f592-20f5-48dd-9295-481b3ffb3c87",
          "created":1710164142000,
          "name":"Brand 1"
          "committed":1710164142001
       },],
    "category":[
       {
          "uuid":"7020f592-20f5-48dd-9295-481b3ffb3c87",
          "created":1710164142000,
          "name":"Categoria 1"
          "committed":1710164142001
       },
    {
       "uuid":"7020f592-20f5-48dd-9295-481b3ffb3c87",
       "created":1710164142000,
       "name":"Categoria 2"
       "committed":1710164142001
    },],
 }

}

Esempio di risposta con format autocomplete:

{

 "result":[
    {"uuid":"7020f592-20f5-48dd-9295-481b3ffb3c87","memo":"Vino 1"},
    {"uuid":"7020f592-20f5-48dd-9295-481b3ffb3c87","memo":"Vino 2"},
 ]

}

Esempio di risposta con format count:

{“result”:127}

Questa api richiede la capability cap_admin, è analoga alla funzione di ricerca ma con le seguenti caratteristiche:

• ricerca su tutti gli oggetti, compresi quelli in stato “GENERATO” e “CANCELLATO”
• non consente di personalizzare la ricerca (non riceve nemmeno un postdata), di conseguenza ritorna sempre gli oggetti così come sono

A differenza delle api viste precedentemente la stessa deve essere implementata sia a livello di modello che a livello di microservizio (in modo da consentire un backup totale o parziale) In questa revisione della specifica non saranno approfonditi aspetti di backup incrementale, di job di materializzazione del backup, o di split dello stesso per accomodarne le risorse di generazione. A tendere questi aspetti dovranno essere presi in considerazione

La risposta potrà essere:

• un array di oggetti
• un oggetto di errore

Esempio di definizione:

“backup”:{“name”:“Backup objects”,“method”:“GET”,“url”:“/api/product/backup/”,“params”:[],“data”:[],“response”:“array”,“capabilities”:{“backup”:[“cap_admin”]}}

Esempio d’uso:

curl -s https://pim.neosidea.com/api/product/backup/

Risposta: {

 "result":[
    {...},
    {...},
    {...},
 ]

}

Questa api richiede la capability cap_admin, è analoga alla funzione di save ma con le seguenti caratteristiche:

• non vengono verificati gli identificativi e, di conseguenza, se mancanti non vengono ripristinati gli oggetti, se presenti non ne viene verificata una precedente generazione
• non vengono effettuati controlli di consistenza
• non viene aggiornato l'oggetto, ad esempio, con una data di ultima modifica

Come l'api di backup la stessa deve essere implementata sia a livello di modello che a livello di microservizio (in modo da consentire un ripristino totale o parziale)

La risposta potrà essere:

• un boolean di conferma
• un oggetto di errore

Esempio di definizione:

“restore”:{“name”:“Restore objects”,“method”:“POST”,“url”:“/api/product/restore/”,“params”:[],“data”:“array”,“response”:“boolean”,“capabilities”:{“restore”:[“cap_admin”]}}

Esempio d’uso:

curl -s -X POST -H “Content-Type: application/json” https://pim.neosidea.com/api/product/backup/ [

 {...},
 {...},
 {...},

]

Risposta:

{“result”:true}

Url: https://pim.neosidea.com/api/manifest.json

Contenuto:

{

 "code":"pim",
 "name":{
    "it":"Gestione delle informazioni dei prodotti",
    "en":"Product Information Management"
 },
 "config":{
 "search_max":100,
 "create_max":100,
 "load_max":100,
 "save_max":100,
 "multiuuid_max":100,
 "uncommitted_max":86400000,
 "locale":[
    "it",
    "en"
 ]

},

 "schema":{
    "manufacturer":{
        "name":{"it":"Produttore"},
        "fields":{
           "name":{"name":"Nome","type":"text","unique":true,"required":true,"sort":true,"search":true,"autocomplete":true}
           "address":{"name":"Indirizzo Postale","type":"text","search":true,}
   {,
   "api":{
   "new":{"name":"Create new objects","method":"GET","url":"/api/manufacturer/create/","params 
   [{"code":"num","name":"Numero","type":"positiveinteger","required":true}],"response":"array","capabilites":{}},
   "save":{"name":"Save objects","method":"POST","url":"/api/manufacturer/save/","params":[],"data":"array","response":"boolean","capabilities":{"commit" 
   ["cap_MODEL_create","cap_MODEL_create_own"],"edit":["cap_MODEL_edit","cap_MODEL_edit_own"],"delete":["cap_MODEL_delete","cap_MODEL_delete_own"]}},
   "load":{"name":"Load objects","method":"POST","url":"/api/manufacturer/load/","params":[],"data":"array","response":"array","capabilites":{}},
   "search":{"name":"Search objects","method":"POST","url":"/api/manufacturer/search/","params":[],"data":"object","response":"array","capabilities":{"search" 
  ["cap_MODEL_search","cap_MODEL_search_own"]}},"backup":{"name":"Backup objects","method":"GET","url":"/api/manufacturer/backup/","params":[],"data":[],"response
  ":"array","capabilities":{"backup":["cap_admin"]}},"restore":{"name":"Restore objects","method":"POST","url":"/api/manufacturer/restore/","params": 
  [],"data":"array","response":"boolean"}
 },
    "sort":{
       "field":"name";
       "desc":false,
    }
 },
 "product":{
 "name":{"it":"Prodotto"},
 "fields":[...]
 "api":[...],
 “ui”:[
    {
       “name”:”Informazioni Principali”,
       “format”:12,
       “fields”:[
         {“field”:”brand”},
         {“field”:”name”},
       ]
    },
 {
    “name”:”Informazioni Aggiuntive”,
    “format”:6,
    “fields”:[
    {“field”:”issinglevintage”},
    {“field”:”year”},]
 }]
    "sort":{
    "field":"committed";
    "desc":true,
 }
 },
    "productvariant":{
    "name":{"it":"VarianteProdotto"},
    "fields":[...],
    "api":[...],
    "firstclass":false,
   "dependson":"product",
 },
 },
    "api":{
    "manifest":{"name":"Micro Service Manifest","method":"GET","url":"/api/manifest.json","params":[],"data":[],"response":"object","capabilities":{}}
    "backup":{"name":"Backup objects","method":"GET","url":"/api/backup/","params":[],"data":[],"response":"array","capabilities":{"backup":["cap_admin"]}}"restore 
    {"name":"Restore objects","method":"POST","url":"/api/restore/","params":[],"data":"array","response":"boolean","capabilities":{"restore":["cap_admin"]}}
 }

}