API Reference Microservizi

Questa api potrà essere pubblicata a qualsiasi url, sarà richiamabile in GET e fornirà al client le seguenti informazioni:

• Elenco puntatoDefinizione del microservizio

Fornirà al cliente informazioni per identificare il microservizio quali:

• codice identificativo
• nome mnemonico

le stesse potranno essere estese in futuro per fornire funzioni di aggregazione/abilitazione automatica, quali, ad esempio: icona, colore, scope (gruppo, capability o progetto).

Esempio:

{“code”:“pim”,“name”:{“it”:“Gestione delle informazioni dei prodotti”,“en”:“Product Information Management”}}

o (di seguito: ogni “nome mnemonico” potrà essere rappresentato come stringa o come oggetto che includa un set di codici di locale (1+) con la stringa equivalente, i codici di locale saranno delle stringhe di 2 caratteri, e rappresenteranno il Set 1 dello standard ISO 639 (ISO639) (Language Codes), quindi limitativi alla rappresentazione di una lingua più che di una cultura o provenienza geografica, la cui inclusione sarà oggetto di valutazioni successive)

{“code”:“pim”,“name”:“Product Information Management”}

Inoltre nello stesso potrà essere presente una sezione “relations” che contenga i microservizi referenziati dallo stesso (in formato codice: manifesto)

Fornirà al client informazioni utili per utilizzare correttamente per le api quali:

• numero massimo di risultati in ricerca
• numero massimo di elementi creabili
• numero massimo di elementi caricabili
• numero massimo di elementi salvabili
• numero massimo di elementi in una relazione multipla
• tempo di riciclo degli oggetti non committati (in millisecondi)
• locale supportati
• tempo massimo di vita degli oggetti non committati
• periodicità di verifica dellifetime degli oggetti
• tempo massimo di vita degli oggetti cancellati
• dimensione massima di una richiesta json (attenzione: questo limite viene applicato anche alla chiamata di restore)

Le stesse potranno essere estese da configurazioni specifiche per microservizio (ad esempio: dimensione massima di un chunk di upload )

Il client non potrà fare assunzioni sul valore delle stesse che sarà oggetto di tuning microservizio per microservizio (ad esempio un microservizio potrà consentire di caricare 1000 oggetti per volta, un altro solo di 10 per ragioni tecniche/di performance/di sicurezza)

Ogni campo sarà rappresentato dalle seguenti proprietà:

• “code”: codice identificativo, sarà utilizzato come chiave
• “name”: nome mnemonico
• “type”: tipo
• “default:” valore di default: statico, con la possibilità di utilizzare per i seguenti campi i seguentivalori dinamici:

uuid: “code di un oggetto”: il backend provvederà a pescare l'oggetto del modello relazionato con quel campo code, e valorizzare il campo con il suo descrittore

nota: se l oggetto relazionato dovesse essere residente su un altro microservizio può essere cachato localmente fino al riavvio del microservizio

date, datetime: “now”: il backend provvedere a calcolare la data, o la data e ora attuali e a valorizzare il campo

non è possibile impostarla per campi “langtext”,“langlongtext” e “uuid[]”

Per valori di default più avanzati occorrerà implementare un event handler nel backend.

L'informazione sul valore di default non potrà mai essere utilizzata da un client (e potrebbe anche essere nascosta allo stesso).

Nota bene: il valore di default non è da intendersi come un'imposizione sulla creazione dell'oggetto, in quanto tale il suo valore può essere variato client-side, per “forzare” il suo valore occorrerà lavorare con un event-handler, in tal senso non è prevista una valorizzazione di default per i campi di sicurezza (es: utente creatore), che saranno forzati e valorizzati con altri metodi.

• Elenco puntato“required”: obbligatorietà ( default: false)
• Elenco puntato“unique”: univocità: per tutti i campi ad eccezione del campo tipo “uuid[]”: significa che non possono esserci, per lo stesso modello, più oggetti con lo stesso valore, per un campo di tipo “uuid[]”: significa che nello stesso campo non possono esserci due valori uguali (default: false, ma per i campi tipo “uuid[]” default: true)
• Elenco puntato“hidden”: campo nascosto (default: false) consentirà di mantenere dei campi interni al microservizio e non utilizzabili all'esterno dello stesso (es: un campo password)
• Elenco puntato“readonly”: campo in sola lettura (default: false) consentirà di mantenere dei campi interni al microservizio e non modificabili all'esterno dello stesso (es: un campo calcolato a backend)
• Elenco puntato“writeonce”: campo impostabile una sola volta (default: false) consentirà di mantenere dei campi interni al microservizio e modificabili all'esterno dello stesso una volta sola (es: un campo username impostato in creazione e non più modificabile)
• Elenco puntato“search”: campo ricercabile: servirà a indicare se è possibile effettuare delle ricerche sul campo
• Elenco puntato“sort”: campo ordinabile: servirà a indicare se è possibile effettuare degli ordinamenti sul campo
• Elenco puntato“autocomplete”: campo ricercabile per funzioni di autocompletamento (la possibilità di specifica di un subset a questo scopo consentirà di migliorare le performance)

Queste proprietà saranno affiancate da altre in future revisioni di questa specifica per accomodare la ricerca full-text (ad esempio il peso, e la ricercabilità).

Esempio:

{

 "brand":{"name":{"it":"Produttore","en":"Manufacturer"},"type":"uuid","model":"brand"},
 "name":{"name":"Nome","type":"text","required":true,"search":true,"sort":true,"autocomplete":true,"unique":true},
 "owner":{"name":{"it":"Utente Proprietario","en":"Owner User"},"type":"uuid","model":"user","origin":"https://sso.neosidea.com/api/Manifest.json"

},

 "year":{"name":"Anno","type":"integer","min":1945}

}

Per consentire all’UI di autogenerare i campi in una maniera organizzata verrà fornita una sezione, detta “ui” di suggerimenti così organizzata:

• Una lista ordinata di definizioni di Sezione, ogni sezione sarà caratterizzata da Nome, formato di visualizzazione dei campi (numero da 1 a 12) e elenco ordinato dei campi
• Per ogni campo verrà riportato in un oggetto il codice campo, così da lasciar aperta la specifica a ulteriori estensioni

L’utilizzo delle stesse è facoltativo, e la gestione di informazioni incoerenti o mancanti è lasciata alla ui (ad es: campi doppi, campi mancanti). Esempio: “ui”:[

 {
    “name”:”Informazioni Principali”,
    “format”:12,
    “fields”:[
       {“field”:”brand”},
       {“field”:”name”},
    ]
 },
 {
    “name”:”Informazioni Aggiuntive”,
    “format”:6,
    “fields”:[
       {“field”:”issinglevintage”},
       {“field”:”year”},
    ]
 }

]

il formato d'errore è un oggetto composto da:

• codice errore (obbligatorio)
• descrizione testuale errore
• parametri errore

Ad esempio:

{“error”:{“code”:“F001”,“description”:“Il campo codice non è univoco”,“params”:[{“field”:“code”}]}}

Ogni api per accedere a un modello sarà descritta in termini di:

• codice identificativo
• nome mnemonico
• verbo http (GET, POST, …)
• url di accesso (assoluta rispetto alla root di dominio del manifest del microservizio o assoluta, quindi, se ad esempio abbiamo un manifest tipo https://pim.neosidea.com/api/Manifest.json, lo stesso potrà specificare url di accesso tipo: /api/product/create/ o https://pim.neosidea.com/api/product/create/
• parametri url: saranno descritti i parametri concatenabili dall'url di accesso in termini di codice identificativo, nome mnemonico, tipo (dal sottoinsieme: text/number/integer/positivenumber/positiveinteger/date/datetime/time/timerange/boolean/uuid ), e obbligatorierà, gli stessi dovranno essere passati codificati in USASCII e separati da un forward slash.
• parametri: saranno descritte le chiavi utilizzabili in un oggetto json trasferibile nel contenuto delle chiamate, in aggiunta ai tipi sin qui visti occorre prevedere i tipi speciali: “array” e “object” che potranno essere utilizzati per trasferire vettori di oggetti, oggetti, oggetti di ricerca, oggetti di risposta, e il tipo “blob” per i trasferimenti binary o opachi alla specifica.
• response
• capabilities richieste (oggetto contenente un array di capabilities in or organizzate per funzione)

Esempio:

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

• Elenco puntatoIn aggiunta alle chiamate standard la stessa potrà prevedere chiamate custom (es: changepassword).
• Il formato della risposta è sempre da intendersi in alternativa al formato d'errore.
• Tutte le risposte potranno essere validate verificando la nullità del JSONPath (JSONPath) $.error.code

Per migliorare l'integrazione delle stesse sarebbe utile evidenziare nel manifest le capabilities necessarie per il possibile utilizzo di una api, di modo che la UI possa mostrare/nascondere le funzioni sulla base del permesso utente, questa funzione sarà aggiunta alla specifica in una futura revisione.