API e integrazioni

Cosa copre questa categoria

Qui stanno quattro lavori affini. Costruire e testare richieste a mano. Documentare un’interfaccia perché altre persone possano usarla. Mettere un gateway davanti a più servizi in modo che chiavi, limiti di frequenza, quote e versioni si comportino ovunque allo stesso modo. Spostare dati tra prodotti che non sono mai stati progettati per parlarsi.

I primi tre sono per i team che rilasciano un’API. Il quarto è per chiunque cucia insieme strumenti acquistati. Entrambi i pubblici finiscono su questo scaffale, ed è per questo che i prodotti sono così diversi tra loro.

L’automazione puramente visuale senza codice appartiene a no-code e automazione. Gli avvisi su un servizio in produzione sono monitoraggio.

I client, e ciò che li distingue oggi

Ogni client invia una richiesta e mostra una risposta. Le differenze stanno più in profondità.

Prima di tutto la gestione degli ambienti: locale, staging, produzione e ciò che un collega esegue sul portatile, con passaggi puliti senza che nessuno modifichi un URL a mano. Poi lo scripting, così un token può essere recuperato prima di una richiesta invece di essere incollato ogni mattina. Poi le asserzioni di test, così una collection diventa qualcosa che un server di build può eseguire.

La collaborazione è il punto su cui le opinioni si dividono. La sincronizzazione cloud è comoda e mette la cronologia delle tue richieste sui server di qualcun altro. Gli strumenti basati su file tengono le collection nel repository accanto al codice, così una modifica si rivede come qualsiasi altra e nessun workspace se ne va con un dipendente in uscita.

In ogni caso chiedi dove stanno i segreti. Una chiave scritta in una collection esportata è la strada standard verso un repository pubblico.

Documentazione che non marcisce

La documentazione scritta a mano è superata entro un trimestre. L’unica soluzione che sopravvive è la generazione da una specifica che vive insieme al codice e si ricostruisce quando il codice viene integrato.

Controlla tre cose: se il prodotto legge il formato della tua specifica senza un passaggio di conversione, se gli esempi si possono eseguire dalla pagina e se le vecchie versioni restano pubblicate per chi le usa ancora.

Un changelog conta più del design. Chi consuma l’API deve sapere cosa si è rotto e quando, e nessuno stile sostituisce questo.

I gateway, e quando ne vale la pena

Un singolo servizio raramente ha bisogno di un gateway. Il caso si presenta quando autenticazione, limiti di frequenza, quote e versionamento devono comportarsi in modo identico su più servizi.

A quel punto le domande sono: dove gira e quanta latenza aggiunge, come si definiscono i limiti e cosa vede chi chiama quando ne raggiunge uno, se le chiavi si possono ruotare senza downtime e cosa contengono i log. Tutto ciò che termina il traffico diventa un rischio di disponibilità a sé, quindi chiedi cosa succede quando è il gateway stesso ad avere una brutta giornata.

Cosa misurano i prezzi

• Utenti nei client e nei prodotti di documentazione, a volte gratuiti per i revisori in sola lettura.
• Attività o esecuzioni nelle piattaforme di integrazione, contate per passo e non per flusso.
• Chiamate o banda nei gateway, con una tariffa separata per ciò che è in cache.
• Conservazione della cronologia delle esecuzioni, breve nei piani di ingresso e breve proprio quando serve.
• Connettori, con quelli premium parcheggiati un livello sopra il piano quotato.

Il prezzo per attività merita un po’ di aritmetica prima della firma. Un flusso di sei passi eseguito ogni dieci minuti non è un’attività al mese, e il numero che diventa ha sorpreso parecchi team. La stessa forma di sorpresa in altre categorie è raccolta in cosa nascondono le pagine dei prezzi.

Cosa provare

Ricostruisci un’integrazione vera che già usi, da capo a fondo, compresa la parte in cui l’altro lato restituisce un errore.

Osserva come lo strumento gestisce i nuovi tentativi, la consegna duplicata, una terza parte che si blocca e un payload che arriva con un campo mancante. I prodotti ben fatti ti permettono di rieseguire un’esecuzione fallita dopo aver corretto la causa. Quelli più deboli la perdono in silenzio e non ti dicono nulla finché non lo fa un cliente.

Poi controlla l’uscita. Collection, specifiche e definizioni dei flussi dovrebbero essere esportabili come file che puoi leggere. Tutto ciò che resta chiuso in un workspace è lavoro che farai due volte.

Documentazione, versionamento e mantenimento dei consumatori

Un’interfaccia con degli utenti è una promessa, e gran parte della difficoltà in questa categoria viene dal cambiarla senza tradire quella promessa.

Decidi un approccio al versionamento prima che arrivi il primo consumatore esterno, perché introdurlo dopo significa chiedere a tutti di cambiare insieme. Qualunque sia lo schema, pubblica cosa è cambiato e quando, e concedi un periodo di deprecazione misurato in mesi e non in settimane.

Gli errori meritano tanta attenzione quanto i successi. Una risposta che dice cosa è andato storto, quale campo l’ha causato e cosa fare dopo elimina più richieste di assistenza di qualsiasi quantità di prosa.

Poi leggi la tua documentazione come la leggerebbe un nuovo arrivato. Il miglioramento più rapido disponibile di solito è un esempio funzionante in cima alla pagina invece di una tabella di riferimento.