menu di navigazione del network

Quali status-code indicare nelle specifiche dell'API?


(Roberto Polli) #1

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