menu di navigazione del network

Header standardizzati per un Ecosistema API affidabile

Un ecosistema API porta ad integrare fortemente sistemi server e client.
Per gestire i problemi ed evitare fallimenti a cascata bisogna scambiare informazioni stato dei servizi ed il carico supportato.

Esempio - Caso di sovraccarico: cittadino -> banca -> servizio di pagamento -> comune

  • Un cittadino vuole pagare la TARI tramite home-banking
  • la banca si interfaccia con un servizio di pagamento che contatta il comune
  • il comune espone un’API per il pagamento della TARI comunale
  • nel giorno di scadenza della TARI, l’endpoint del comune va’ in sovraccarico e non riesce a gestire tutte le richieste:
    • parte delle richieste andranno in errore
    • altre supereranno il timeout impostato dal servizio di pagamento e/o dal sito della banca
    • una piccola parte verrà servita nei tempi stabiliti

Vanno fatti quindi dei piani di emergenza per gestire le situazioni di errore e/o sovraccarico.

Il protocollo HTTP mette a disposizione due strumenti semplici e potenti:

Per segnalare le politiche di throttling basta inviare per ogni risposta i seguenti header:

X-RateLimit-Limit: limite massimo di richieste per un endpoint
X-RateLimit-Remaining: numero di richieste rimanenti fino al prossimo reset
X-RateLimit-Reset: il numero di secondi mancante al prossimo reset

In questo modo i client potranno regolare il numero di richieste da inviare.

**ATTENZIONE: questi tre header, qui nella versione più diffusa, sono utilizzati anche con leggere variazioni. I client devono gestire queste variazioni, ma chi eroga in un Ecosistema API deve adottare una sintassi comune! **

Si possono segnalare problemi di sovraccarico ritornando HTTP 503 quando il sistema si accorge di non riuscire ad erogare il servizio secondo le deadline previste: questo pattern si chiama Circuit-Breaker (in italiano: fusibile).

Gli status che evidenziano un sovraccarico devono essere ritornati quanto prima:

  • HTTP 429 (too many requests) se il rate limit viene superato
  • HTTP 503 (service unavailable) in caso di servizio indisponibile (eg. in manutenzione) o di sovraccarico

Per differire le richieste, si dovrebbe sempre usare l’header

- Retry-After: numero di secondi dopo i quali ripresentarsi

anche implementando meccanismi di exponential back-off.

A Retry-After e X-RateLimit-Reset vanno assegnati valori in secondi, eventualmente aggiungendo un po’ di jitter per evitare che gruppi di client si presentino contemporaneamente.

Si può anche pensare di “rimbalzare” le richieste in eccesso anche se il sistema non è sovraccarico: una lettura utile è The Global Chubby Planned Outage dal libro Google SRE

L’utilizzo di header uniformi è importantissimo:

  • semplifica lo sviluppo dei client, riducendo gli errori;
  • evita di verificare l’esistenza di header sempre diversi.
2 Likes