Strumenti

Termini tecnici dell’accordo di servizio CART

Le applicazioni che si integrano al CART per accedere a determinate API, hanno ricevuto le credenziali di accesso e quindi le autorizzazioni necessarie per effettuare le proprie richieste. Oltre a tutte le implicazioni tecniche, legate alla natura del servizio ed ai vincoli di sicurezza, che dovranno essere indirizzate dagli sviluppatori degli applicativi, ci sono ulteriori caratteristiche tecniche, proprie degli aspetti di gestione del CART, che devono essere conosciute, accettate e gestite dagli applicativi client.

Occorre innanzitutto distinguere i seguenti casi:

  • API con interazione sincrona, dove è prevista la ricezione, da parte dell’applicativo client, della risposta del servizio sulla medesima connessione avviata con la richiesta.
  • API con interazione asincrona, dove è prevista la presa in carico della richiesta da parte del CART. Sarà compito del CART gestire in una fase successiva la consegna della richiesta al servizio destinatario.

Vediamo il dettaglio dei due casi.

API con interazione sincrona

Alle richieste inviate dagli applicativi client il CART assegna un identificativo interno, X-CART-id, che viene restituito al client con la risposta.

È richiesto che l’applicativo client acquisisca e conservi l’identificativo CART della transazione al fine di poterlo utilizzare per il tracciamento delle proprie richieste. Tale identificativo servirà ad indirizzare efficacemente l’indagine diagnostica, nel caso di problematiche riscontrate sulle quali si intende ricevere supporto.

In alcune situazioni anomale può accadere che il CART non restituisca l’identificativo della transazione, in tal caso l’applicativo deve considerare la richiesta come “non presa in carico”. A seconda dell’errore ottenuto, l’applicativo deve stabilire se sia necessaria una rispedizione della richiesta. Si presenta la seguente casistica:

  • Errori permanenti: sono i casi in cui l’applicativo non deve procedere con la rispedizione della richiesta poiché l’errore riscontrato non si risolverà. Tali errori sono associati ai seguenti codici HTTP di ritorno: 400, 401, 403, 404, 409, 429 (Rate Limiting – Limit Exceeded)
  • Errori temporanei: sono i casi in cui la problematica riscontrata può essere causata da un problema temporaneo. In questi casi ha senso che l’applicativo proceda con la rispedizione della richiesta. Tali errori sono associati ai seguenti codici HTTP di ritorno: 429 (Rate Limiting – Too Many Requests), 502, 503, 504. Nei casi HTTP 502 e 504 occorre prestare attenzione che per le operazioni di scrittura sia garantita l’idempotenza, altrimenti si rischia di creare duplicazioni.

API con interazione asincrona

Le richieste inviate per questo tipo di API prevedono la restituzione dell’identificativo CART a conferma della presa in carico del messaggio.

La mancata restituzione dell’identificativo può essere gestita, per stabilire l’eventuale rispedizione, in maniera analoga a quanto descritto per le API con interazione sincrona.

La presa in carico del messaggio da parte del CART significa che sarà l’infrastruttura ad occuparsi della consegna, in modalità asincrona, al servizio destinatario.

Dovendo il CART mantenere il messaggio preso in carico per il tempo necessario alla sua consegna, è necessario che le politiche di gestione delle richieste lato client tengano conto dei seguenti limiti:

  • Consegna in modalità “Trasparente”: cioè nei casi in cui il CART consegna la richiesta direttamente all’endpoint del servizio destinatario. In questi casi il limite di tenuta del messaggio sul CART è di 5 giorni.
  • Consegna in modalità “Integration Manager”: cioè nei casi in cui il CART tiene in una “Message Box” la richiesta in attesa che il servizio erogatore la prelevi. In questi casi il limite di tenuta del messaggio sul CART è di 15 giorni.

Trascorsi i limiti di tempo suddetti, i messaggi vengono cancellati e quindi non potranno più essere consegnati all’erogatore del servizio.