Integrazione degli applicativi
Gli API Gateway del 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. Pertanto gli applicativi continuano ad operare sostanzialmente come se stessero interagendo direttamente con l’applicativo che implementa l’API, a meno della URL invocata dai client, che diventa quella del Gateway, anziché quella del servizio finale.
Ci sono tuttavia alcune informazioni aggiuntive che è utile che il Gateway possa trasmettere agli applicativi con cui interagisce, sia ai client che invocano le API che alle implementazioni delle API a cui vengono girate le richieste applicative.
Integrazione degli applicativi server
Nel caso degli applicativi server, i Gateway del CART, per ogni richiesta gestita, introducono i seguenti header HTTP nella richiesta HTTP girata alla 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 sul 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/o i seguenti header CART aggiuntivi contenenti le informazioni presenti nel token.
| Header Name | Header Value |
|---|---|
| X-CART-fiscalNumber X-CART-name X-CART-familyName X-CART-email X-CART-ivaCode | informazioni estratte dalla chiamata alla UserInfo, se prevista |
| X-CART-oauthClientId | identificativo dell’applicazione client che ha generato il token Oauth |
| X-CART-username | contenuto del claim preferred-username |
| X-CART-scope | elenco degli scope, separati con una virgola, eventualmente presenti nel token Oauth |
| X-CART-roles | elenco dei ruoli dell’utente, separati da virgola. In questa modalità vengono forniti soltanto i ruoli di un utente e non i relativi attributi |
Integrazione degli applicativi client
Nel caso degli applicativi client, i Gateway CART, per ogni richiesta in arrivo introducono il seguente header HTTP nella risposta restituita al client:
- X-CART-id, valorizzato con un identificativo unico di transazione generato dal CART;
Il Gateway può inoltre produrre, in caso di anomalie nella gestione della richiesta, due diverse tipologie di errori:
- Errori Client: identificabili da un codice http 4xx 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 (es. 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 dal CART permette alle applicazioni client di discriminare tra errori causati da una richiesta errata, per i quali è quindi necessario intervenire sull’applicazione client 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 / SOAP | GovWay-Transaction-ErrorType | Retry |
|---|---|---|
| 400 / Client | Errori 400 (Bad Request) | No |
| 401 / Client | Errori 401 (Authentication Error) | No |
| 403 / Client | Errori 403 (Authorization Deny) | No |
| 404 / Client | Errori 404 (NotFound) | No |
| 409 / Client | Errori 409 (Conflict) | No |
| 429 / Client | LimitExceeded – Errori 429 (Rate Limiting) | No |
| 429 / Client | TooManyRequests – Errori 429 (Rate Limiting) | Sì |
| 502 / Server | Errori 502 (Bad Gateway) | Sì se idempotente |
| 503 / Server | Errori 503 (Service Unavailable) | Sì |
| 504 / Server | Errori 504 (Endpoint Request Timed-out) | Sì se idempotente |
Nei casi in cui è prevista la rispedizione, GovWay genera un header “Retry-After” che indica al client il numero di secondi di attesa prima di ripetere la richiesta.