API Reference Microservizi

Per funzionare il sistema avrà bisogno dei seguenti microservizi “di bootstrap”, gli stessi non sono necessari a un funzionamento di base, ma serviranno per un utilizzo completo:

Esporrà i modelli Capabilities (importate dai manifest dei microservizi), Applications, Groups, Users, Sessions (in un ottica di multi-tenancy potrebbe esporre anche la stessa). E' il centro stella del sistema, motivo per il quale i microservizi devono cachare le sue risposte per la durata di vita dei token. Offre un servizio oauth di autenticazione applicativa. Offre un servizio oauth di autenticazione utente. Offre un api per ottenere l'identità e le capabilities relative a un token. Non sono previste dalla presente gestione dello scoping delle informazioni.

Gli endpoint che lo stesso offrirà per l'autenticazione OAuth saranno /api/session/authorization e /api/session/token, inoltre metterà a disposizione una chiamata /api/session/tokeninfo per ispezionare un token.

1) Autenticazione Server Side (Trusted Client): client_credentials:

1a) Richiesta token, dato un applicativo con client_id=MYTRUSTEDCLIENT e client_secret=XXYYZZ
	NB: client_id se client_secret possono esser passati sia come Authentication: Basic (come suggerito dalla specifica, quindi codificati assieme in base64), sia nel formdata

	curl -s -X POST --basic --user MYTRUSTEDCLIENT:XXYYZZ -H "Content-Type: application/x-www-form-urlencoded" https://AAA_DOMAIN/api/session/token -d '&grant_type=client_credentials'
	{
		"access_token":"02f445c40e58dcae7977207898319226477998df6a3cef21f831e2546da38d17",
		"token_type":"bearer",
		"expires_in":3599
	}

1b) (facoltativo) Verifica token
	Fuori specifica, ispirato dall'interfaccia di google

	curl -s -X POST -H "Content-Type: application/x-www-form-urlencoded" https://AAA_DOMAIN/api/session/tokeninfo?access_token=02f445c40e58dcae7977207898319226477998df6a3cef21f831e2546da38d17|json_pp
	{
		"application" : "7a3c660e-c1de-4d4c-acdc-c15ee27728af",
		"capabilities" : ["29cb67d2-2620-4db0-a712-6499ed17857d"],
		"expires_in" : 1338716
	}

2) Autenticazione Client side (Untrusted Client): Authorization Grant with PKCE

2a) Redirezione alla pagina di login con:
		client_id=MYUNTRUSTEDCLIENT (NO CLIENT SECRET, UNTRUSTED CLIENT)
		state=1234
		scope=(niente)
		redirect_uri=(il tuo url di callback DEVE ESSERE LO STESSO IMPOSTATO NELLA TABELLA DEI CLIENT)
		code_challenge= il base64 dello sha256 di un valore casuale che il client deve salvarsi!!!!
		code_challenge_method=S256 (accetto solo questo valore)
	https://AAA_DOMAIN/api/session/authorize?client_id=aaaui&response_type=code&state=1234&redirect_uri=https://MYUNTRUSTED_DOMAIN/cb&scope=&code_challenge=jZae727K08KaOmKSgOaGzww/XVqGr/PKEgIMkjrcbJI%3D&code_challenge_method=S256

2b) se l'utente sbaglia qualcosa lo redirigo indietro sull'url di callback con l'errore:

	https://MYUNTRUSTED_DOMAIN/cb?error=unauthorized_client&state=1234

2c) se l'utente fa login lo redirigo indietro sull'url di callback con il CODE:

	https://MYUNTRUSTED_DOMAIN/cb?code=J3w6rU5ZUXmLQBqUWSK8sI4I%2Fy9murtowaARj%2FW66bE%3D&state=1234

2d) Il client a questo punto deve scambiare il code con un access_token:
	NB: nel campo code_verifier viene passato il valore in chiaro che è stato usato per generare il code_challenge!

	curl -s -X POST -H "Content-Type: application/x-www-form-urlencoded" https://AAA_DOMAIN/api/session/token -d 'grant_type=authorization_code&client_id=aaaui&code=J3w6rU5ZUXmLQBqUWSK8sI4I%2Fy9murtowaARj%2FW66bE%3D&code_verifier=123456&redirect_uri=https://MYUNTRUSTED_DOMAIN/cb
	{
		"access_token":"l3pz/eCm4/zjMLzgdIJ237F5BNV97oCYCzbxOiRsDKQ=",
		"token_type":"bearer",
		"expires_in":3599,
		"refresh_token":"pjdjjrY2P+vDqoY1hkRradAhKr4SlLPVFo4h2kdnVpo="
	}

2e) (facoltativo) Verifica token (come sopra):
	curl -s -X POST -H "Content-Type: application/x-www-form-urlencoded" https://AAA_DOMAIN/api/session/tokeninfo?access_token=l3pz/eCm4/zjMLzgdIJ237F5BNV97oCYCzbxOiRsDKQ%3D|json_pp
	{
		"user":"14be8ee0-cc1c-45bb-a4af-a21ebbeb7917",
		"application":"356edc11-a574-463b-9037-bcb4a673ca83",
		"expires_in":2646672,
		"scope":"",
		"capabilities":["29cb67d2-2620-4db0-a712-6499ed17857d"]
	}

2f) Il client usa l'access_token per effettuare le chiamate aggiungendolo all'header:

	axios.post('/qualcosa',{mydata},{headers:{'Authorization':'Bearer '+access_token}}

2g) Prima della scadenza, il client scambia il refresh token per una nuova coppia di token:
	curl -s -X POST -H "Content-Type: application/x-www-form-urlencoded" https://AAA_DOMAIN/api/session/token -d 'grant_type=refresh_token&client_id=aaaui&refresh_token=pjdjjrY2P%2BvDqoY1hkRradAhKr4SlLPVFo4h2kdnVpo%3D'|json_pp
	{
		"access_token" : "Bk8RGTcjRWT0fWj40/yOv7BY39x6CXRAlRDOXacTy9Q=",
		"expires_in" : 3599,
		"refresh_token" : "xYosC0BRKq4vMsFOaWxifBXdtX4S0psWbIfISfpPeDs=",
		"token_type" : "bearer"
	}

2h) Per verificare le capabilities fornite:
	curl -s -X POST -H "Content-Type:application/json" https://AAA_DOMAIN/api/capability/load -d '["29cb67d2-2620-4db0-a712-6499ed17857d"]'|json_pp
	{
	   "result" : {
	      "29cb67d2-2620-4db0-a712-6499ed17857d" : {
	         "code" : "cap_admin",
	         "committed" : 1711745887706,
	         "created" : 1711745887701,
	         "model" : "capability",
	         "modified" : 1711745887708,
	         "name" : "cap_admin",
	         "uuid" : "29cb67d2-2620-4db0-a712-6499ed17857d"
	      }
	   }
	}

Esporrà un modello Log, sarà utilizzabile con l'api già presentata. Categorizzerà i log nelle seguenti categorie:

• debug
• notice
• warning
• error
• legal
• perf
• perf_start
• perf_end

Deve garantire un funzionamento diffserv all'interno del quale:

• siano garantiti i log di tipo legal
• siano sufficientemente garantiti i log di tipo error
• sia in grado di macinare in best-effort le altre categorie secondo la priorità warning>notice>debug>perf>perf_start>perf_end

I log di tipo perf_start e perf_end sono log transitori utili alla generazione dei log perf

Per loggare le chiamate il microservizio esporrà quindi degli shortcut per salvare direttamente i log per tipologia

curl -s -X POST -H “Content-Type: application/json” https://LOG_DOMAIN/api/log/LOGTYPE -d “[{“description”:“Prova”}]”;

Esporrà un modello Resource, che rappresenterà un file caricato da un utente.

In tal senso nell'architettura è l'unico microservizio che necessita di accedere a un disco, centralizza e semplifica la gestione sistemistica e delle risorse. Oltre all'api succitata offrirà un api di upload a chunk di dati binari, referenzierà tramite url la risorsa che deve essere depositata di default su uno spazio sufficientemente randomico, ma alla quale dovrà poter esser associato un pretty url (non richiesto, un tiny url), la risorsa dovrà poter essere prelevata anche tramite cdn, può restare non disponibile fino a quando il modello non è in stato ACTIVE.

per caricare una risorsa si potrà:

1) Generare una risorsa

curl -s -X POST https://MEDIA_DOMAIN/api/resource/create/1

2) (Facoltativo) Impostarne le proprietà

curl -s -X POST -H "Content-Type: application/json" -H "Authorizazion: Bearer Bk8RGTcjRWT0fWj40/yOv7BY39x6CXRAlRDOXacTy9Q=" https://MEDIA_DOMAIN/api/resource/save/ -d "[{"uuid":"29cb67d2-2620-4db0-a712-6499ed17857dd","filename":"prova.jpg","mimetype":"image/jpeg","parent_uuid":"356edc11-a574-463b-9037-bcb4a673ca83","parent_model":"product","parent_origin":"pim"}]"

3) Uploadare dei chunk di file

Attenzione: i chunk devono essere caricati strettamente in sequenza (attendendo il completamento dell'upload del chunk precedente).
Attenzione: i chunk dovranno essere codificati in Base64 e inseriti in un oggetto json con una chiave "chunk"
Attenzione: i chunk devono stare all'interno del limite di dimensione massima del json di richiesta

curl -s -X POST -H "Content-Type: application/json" -H "Authorizazion: Bearer Bk8RGTcjRWT0fWj40/yOv7BY39x6CXRAlRDOXacTy9Q=" https://MEDIA_DOMAIN/api/resource/upload/29cb67d2-2620-4db0-a712-6499ed17857dd -d '{"chunk":"AAbb=="}'

4) Committare il file con i dati

(uguale a 2) + committed)
Attenzione! dopo che sarà committata la risorsa sarà in sola lettura!

curl -s -X POST -H "Content-Type: application/json" -H "Authorizazion: Bearer Bk8RGTcjRWT0fWj40/yOv7BY39x6CXRAlRDOXacTy9Q=" https://MEDIA_DOMAIN/api/resource/save/ -d "[{"uuid":"29cb67d2-2620-4db0-a712-6499ed17857dd","filename":"prova.jpg","mimetype":"image/jpeg","parent_uuid":"356edc11-a574-463b-9037-bcb4a673ca83","parent_model":"product","parent_origin":"pim","committed":1}]"

Per scaricare una risorsa:

curl -s https://MEDIA_DOMAIN/api/resource/download/29cb67d2-2620-4db0-a712-6499ed17857dd

Consentirà di gestire delle Job Queue FIFO a priorità differenziata, ancora da definire.