Strumenti

Aspetti tecnici dell’integrazione applicativa

Gli API Gateway di CART espongono le stesse interfacce applicative native dei servizi, così come definite dalle interfacce applicative espresse in linguaggio WSDL nel caso di API SOAP e OpenAPI nel caso di API REST. Gli applicativi continuano ad operare come se stessero interagendo direttamente con l’applicativo che implementa la API, a meno che la URL invocata dal client non sia quella del gateway anziché quella del servizio finale.

Ci sono tuttavia informazioni aggiuntive che il gateway può trasmettere agli applicativi con cui interagisce, sia ai client che invocano le API che alle implementazioni delle API a cui sono girate le richieste applicative.

Modalità di integrazione di applicativi server

Nel caso degli applicativi server, i Gateway di CART introducono i seguenti header nella richiesta HTTP girata all’implementazione della API:

  • ‘X-CART-id’,valorizzato con un identificativo unico di transazione generato dal CART;
  • ‘X-CART-clientId’,valorizzato con il nome con cui è stato censito su CART l’applicativo che ha originato la richiesta.

Nel caso la richiesta sia di tipo OAuth, all’implementazione della API potrà essere fornito il token originale e i seguenti header CART aggiuntivi contenenti le informazioni presenti nel token.

Header NameHeader Value
X-CART-fiscalNumber, X-CART-nameInformazioni estratte dall’access token, se presenti.
X-CART-familyName, X-CART-email, X-CART-ivaCode
X-CART-oauthClientIdIdentificativo dell’applicazione client che ha generato il token Oauth.
X-CART-scopeElenco degli scope, separati con una virgola, eventualmente presenti nel token Oauth.
X-CART-rolesElenco dei ruoli dell’utente, separati da virgola. In questa modalità vengono forniti soltanto i ruoli di un utente e non i relativi attributi.

Modalità di Integrazione di applicativi client

Per ogni richiesta proveniente da applicativi client i gateway CART introducono nella risposta il seguente header HTTP: ‘X-CART-id’, valorizzato con un identificativo unico di transazione generato da CART. Il gateway può produrre inoltre, in caso di anomalie nella gestione della richiesta, due diverse tipologie di errori:

  • Errori Client, identificabili da un codice HTTP4XX su API REST o da un fault code di tipo “client” su API SOAP. Indicano che sono stati rilevati dal gateway problemi nella richiesta ricevuta dal client (ad esempio: errore autenticazione, autorizzazione, validazione contenuti…).
  • Errori Server, identificabili dai codici HTTP 502, 503 e 504 per le API REST o da un fault code “server” generato dal gateway e restituito con codice HTTP 500 per le API SOAP.

Per ciascun errore il gateway riporta le seguenti informazioni:

  • lo “status code” HTTP per le API REST o il fault code per le API SOAP;
  • un codice di errore, indicato nell’header HTTP “GovWay-Transaction-ErrorType”, che riporta l’errore rilevato dal gateway (es. AuthenticationRequired, TokenExpired, InvalidRequestContent …);
  • un payload HTTP, contenente maggiori dettagli sull’errore, opportunamente codificato come “Problem Details” per le API REST o “Soap Fault” per le API SOAP.

La codifica degli errori prodotta da CART permette alle applicazioni client di discriminare tra errori causati da una richiesta errata, per i quali è quindi necessario intervenire sull’applicazione prima di effettuare nuovi invii, ed errori dovuti allo stato dei servizi invocati, per i quali è invece possibile continuare ad effettuare la richiesta come dettagliato nella tabella seguente.

REST, SOAPGovWay, Transaction, ErrorTypeRetry
400/clientErrori 400 (Bad Request)No
401/clientErrori 401 (Authentication Error)No
403/clientErrori 403 (Authorization Deny)No
404/lientErrori 404 (Not Found)No
409/clientErrori 409 (Conflict)No
429/clientLimitExceeded, Errori 429 (Rate Limiting)Si
429/serverTooManyRequests, Errori 429 (Rate Limiting)Si
502/serverErrori 502 (Bad Gateway)Si
503/serverErrori 503 (Service Unavailable)Si
504/serverErrori 504 (Endpoint Request Timed-out)Si