Adeguamento degli errore del Gateway al modello di interoperabilità (RFC 7807)

[andreapoli]

Gli errori generati autonomamente dal Gateway e non previsti nelle interfacce del servizio target (es: autorizzazione, validazione, etc.) non sono attualmente aderenti alle linee guida indicate nell'api-starter-kit per la modalità REST, per quanto riguarda il formato del messaggio ritornato al client. GovWay è invece già aderente per quanto concerne i codici e gli header http utilizzati (es. X-RateLimit- *).

Si prevede l'adeguamento all'utilizzo del formato json-problem per soddisfare il modello di interoperabilità. Tra la casistica degli errori codificati nell'api-starter-kit utilizzabili per mappare gli errori generati da GovWay non sono stati riscontrati errori espliciti per gestire le casistiche 401 e 403 i quali ricadono nella categoria di 'default'.

[andreapoli]

@ioggstream riguardo alle casistiche 401 e 403 non sarebbe utile definire delle risposte ad hoc simili a quanto avete fatto per '400BadRequest' e '404NotFound' ? In tal modo, se utilizzati nelle specifiche OpenAPI, rientrerebbero tra gli errrori attesi in modo esplicito dai client.

[ioggstream]

@andreapoli Provo ad illustrare il ragionamento fatto. Suggerimenti ben accetti.

Fai sapere se ti torna: il punto è bilanciare leggibilità e chiarezza.

Vedi anche qui

Premessa

• è corretto gestire 401 e 403 con json-problem
• le API dello starter-kit sono aperte e non ritornano 401 e 403, quindi non sono stati inseriti nell'interfaccia

Discussione

Ci sono diversi tipi di errore:

• errori applicativi funzionali all'API (eg. sono associate a codici di errore, documentazione, ...)
• errori che richiedono spiegazioni specifiche utili al client
• errori con un significato ben definito (404, 405, 412, ...)
• errori solitamente fuori l'ambito applicativo dell'api, eg ritornati dagli apigw (401,403,407,429)

Come decidiamo se indicare un errore nell'API? Bilanciando utilità e funzionalità.

1- tutti gli STATUS di successo vanno indicati 2- tutti gli STATUS associati ad errori utili al client a correggere il tiro vanno indicati 3- gli errori ritornati al di fuori all'ambito applicativo vanno indicati SE fanno parte di un contratto specifico (ad esempio 429 e 503 nel ModI2018 hanno una semantica specifica con header co.) 4- gli STATUS semanticamente chiari (eg. 404) vanno indicati SE fanno effettivamente parte dell'interfaccia - tipo "la fattura in questione non esiste" 5- gli STATUS semanticamente chiari (eg. 401, 403, ...) possono non essere indicati se il modello di risposta non fa' parte dell'interfaccia dell'API

[andreapoli]

@ioggstream il ragionamento mi sembra chiaro.