Un'API definisce il modo in cui un software richiede dati o un'azione a un altro. Consente a un sito di creare un contatto nel CRM, a un servizio di pagamento di comunicare un esito o a un'app mobile di consultare un conto. Un'API utile non è soltanto una raccolta di indirizzi: è un contratto su dati, permessi, errori e cambiamenti.
Partire dalle azioni reali
Individua gli eventi aziendali e i dati necessari all'integrazione. Dai nomi chiari alle operazioni e restituisci solo le informazioni richieste. Descrivi gli input accettati, le possibili risposte e i casi di errore. Documentazione ed esempi devono corrispondere al servizio distribuito, non a una specifica ideale ormai superata.
La sicurezza è parte del contratto
Autentica chi chiama e verifica il permesso su ogni record specifico, non solo il ruolo generale dell'utente. Limita la frequenza delle richieste e convalida tutti i dati in ingresso. Conserva le chiavi segrete su server affidabili. Registra le operazioni che modificano denaro, autorizzazioni o dati dei clienti.
Aspettarsi reti imperfette
Una richiesta può scadere anche se l'altro servizio ha già completato il lavoro. Rendi idempotenti le scritture importanti: un nuovo tentativo non deve creare ordini o addebiti duplicati. Definisci timeout e regole di ripetizione. Per gli eventi, registra i tentativi di consegna e consenti di ripetere quelli falliti.
Preparare i cambiamenti
Client e servizi raramente vengono aggiornati nello stesso istante. Preferisci modifiche compatibili, assegna versioni alle rotture necessarie e controlla quali client usano ancora il comportamento precedente. Un'API ben mantenuta permette al prodotto di evolversi senza trasformare ogni integrazione in una fragile eccezione.
