Riassumo in questo post alcune considerazioni su quali HTTP STATUS indicare nelle specifiche
OAS3. Visto che abbiamo definito nei template gli status 400, 404, 429 e 503, molti si sono chiesti:
perché non definire anche 401 e 403? Ed i 3xx?
Il ragionamento fatto vuole bilanciare leggibilità e chiarezza, come suggerito anche qui
Premessa:
- è corretto gestire 401 e 403 con problem+json
- le API dello starter-kit non sono autenticate 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