La mentalità della piattaforma nella gestione dei prodotti API

Non è un segreto che la pandemia abbia notevolmente amplificato la necessità per le organizzazioni di adottare una strategia digital-first. Le trasformazioni digitali che erano state depriorizzate a favore di altri obiettivi organizzativi si sono spostate in primo piano durante la notte, con un'urgenza senza precedenti. Secondo un McKinsey Global Survey del 2020 sui dirigenti, le aziende hanno accelerato la velocità con cui hanno digitalizzato le operazioni interne e ampliato i portafogli di prodotti digitali di diversi anni, nonostante le sfide significative poste dal COVID-19.

Al centro di queste trasformazioni digitali c'è l'integrazione, facilitata dalle API (Application Programming Interface). Un tempo considerate semplicemente come "messaggeri" o "intermediari" che trasmettevano dati tra sistemi software, le API sono ora riconosciute come il "tessuto connettivo" degli ecosistemi digitali, offrendo integrazione illimitata e opportunità di business alle organizzazioni che le costruiscono e le sfruttano. A causa del potenziale unico rappresentato dalle API, i product manager che supervisionano il loro sviluppo devono adottare un approccio che sblocchi il loro valore latente, uno che enfatizzi la flessibilità e l'estendibilità per garantire esperienze di integrazione impeccabili.

Fare di più con meno

Anche prima dell'ultimo anno senza precedenti, il valore delle API per le organizzazioni era stato ben documentato e l'economia delle API prosperava da tempo. Per comprendere il panorama odierno delle integrazioni, è utile esplorare le origini della filosofia Best of Breed (BoB). Prima degli anni '90, i fornitori di software commercializzavano soluzioni di suite ERP (Enterprise Resource Planning) che tentavano di risolvere un'ampia varietà di sfide organizzative. Queste suite sono diventate sempre più ingombranti e poco pratiche, poiché non sono riuscite a risolvere i casi d'uso specifici dell'organizzazione. Di conseguenza, i fornitori hanno iniziato a creare strumenti più mirati che risolvevano le sfide per un'area funzionale, invece di suite più grandi che tentavano di fare tutto per tutti. Le aziende hanno accolto con favore l'idea di scegliere tra una varietà di strumenti più piccoli e specializzati e hanno iniziato ad assemblare raccolte di soluzioni individuali che meglio si adattavano alle loro esigenze particolari.

Unire i punti

Quando l'approccio BoB ha preso piede, le integrazioni sono diventate una parte cruciale delle strategie di prodotto. Uno strumento in grado di risolvere i problemi di un'area aziendale doveva essere in grado di integrarsi bene con altri prodotti BoB che avrebbero potuto essere utilizzati insieme ad esso. Prendi in considerazione HubSpot, il software di vendita e CRM implementato dalle organizzazioni per monitorare e ottimizzare le pipeline di vendita e le relazioni con i clienti. HubSpot si integra prontamente con altri software BoB come DocuSign (firme digitali), Twilio (notifiche e-mail/SMS) e Zendesk (assistenza clienti) senza richiedere ulteriore sviluppo da parte dei team di progettazione del cliente.

La necessità di strumenti complementari per collegarsi senza problemi l'uno all'altro è stata accompagnata da un passaggio a livello di settore verso l'adozione dell'apertura anziché limitare le interazioni tra i sistemi. Da qualche parte lungo la strada, il numero di integrazioni supportate da un prodotto è diventato una metrica degna di essere commercializzata.

La proposta di piattaforma

Il vero valore delle integrazioni, tuttavia, va oltre la loro capacità di coordinare strumenti e sistemi disparati. Nella migliore delle ipotesi, le API sono il meccanismo collettivo per trasformare i prodotti in piattaforme. I prodotti, per definizione, sono strumenti che hanno un'applicazione specifica; quindi "app". Sono limitati nella loro capacità di creare più proposte di valore e, per estensione, più flussi di entrate. Le piattaforme, d'altra parte, aggiungono valore in un modo diverso: fornendo lo strato infrastrutturale su cui è possibile costruire numerosi prodotti.

Le API aprono nuovi canali di business sfruttando l'esperienza delle terze parti che le sfruttano. Gli sviluppatori consumatori possono progettare un'app immobiliare che utilizza le API Places di Google Maps per aiutare gli utenti a cercare casa, oppure possono sfruttare le API Flight di Skyscanner e le API Hotel di Expedia per creare un sito di ecoturismo specializzato in viaggi in una località specifica. Questi sviluppatori e partner esterni traggono vantaggio dall'accesso ai dati e ai servizi esistenti che possono adattare alle loro attività e i proprietari di API come Expedia ampliano la loro portata e monetizzare opportunità che non esisterebbero se avessero continuato, ad esempio, a elencare solo gli hotel sul loro prodotto.

Rendendolo modulare

Per i leader di prodotto, lo sviluppo di una strategia API di successo richiede un cambiamento di mentalità dal pensiero del prodotto al pensiero della piattaforma. Ciò significa creare prodotti in modo modulare e aperto che consenta la ricombinazione delle loro funzionalità e che dia priorità alla flessibilità per gli sviluppatori che consumano. Pensa ai sistemi di scaffalature IKEA, che i clienti possono acquistare, assemblare e personalizzare in diversi modi per soddisfare una varietà di esigenze. I buoni product manager API vedono le API per quello che sono: strumenti per scalare il business e sviluppare partnership preziose. Riconoscere questo potenziale significa implementare le migliori pratiche per garantirne l'adozione.

Deliziare gli sviluppatori

Se c'è un pilastro fondamentale di una solida strategia API, è l'esperienza dello sviluppatore (DX). Per le integrazioni API, i product manager dei "clienti" devono soddisfare gli sviluppatori consumando. Questi sono gli utenti che alla fine chiamano/si integrano con un'API, i potenziali partner che possono aiutare a realizzare una visione da prodotto a piattaforma. Etichettare la loro esperienza "DX" invece di "UX" riconosce che non sono utenti finali tipici: sono tecnicamente molto più abili. Per entrare in empatia con loro, è essenziale comprenderne i bisogni e le aspettative specifiche.

Migliori pratiche

Le seguenti, sebbene non rappresentino in alcun modo un elenco esaustivo, sono pratiche essenziali per la creazione di API di prim'ordine che garantiscono esperienze di integrazione prevedibili, coerenti e prive di attriti per gli sviluppatori che consumano. I product manager dovrebbero avvicinarsi alla progettazione delle API in modo scalabile, definendo un framework di best practice e pubblicandolo come un documento a cui i team possono fare riferimento durante la creazione di nuove API.

Convenzioni di denominazione ed endpoint coerenti

La definizione di convenzioni di denominazione coerenti per gli endpoint API che identifichino chiaramente la natura e lo scopo dell'API elimina l'ambiguità e contribuisce a una DX positiva e prevedibile. È meglio scegliere un URL di base comune per tutte le API e un framework per l'URL finale che eviti il ​​gergo e le abbreviazioni. Le API nordiche offrono un utile elenco di suggerimenti per la denominazione degli endpoint.

Strutture dettagliate di risposta al successo e al fallimento

Gli sviluppatori desiderano e si aspettano oggetti dati e codici di stato familiari per risposte di successo e di errore. Ciò significa un codice di stato 2xx per scenari di successo, un codice 4xx per errori lato client e un codice 5xx per errori lato server. Tuttavia, la specificità è fondamentale. Una chiamata a un'API "invia e-mail" che restituisce semplicemente una risposta 4xx senza informazioni aggiuntive rende l'esperienza dello sviluppatore scadente, perché conferma semplicemente che l'errore era nella richiesta del client senza fornire ulteriori informazioni su cosa è andato storto esattamente.

 { "status": 400, "message": "incorrect request" }

Al contrario, una risposta che offre dettagli specifici in formato leggibile e sotto forma di codice di errore univoco può aiutare gli sviluppatori a decidere rapidamente come correggere lo scenario di errore, scrivere codice per risolvere il problema e riprovare a chiamare l'API.

 { "status": 400, "message": "To recipient not specified", "code": 21221 }

Per una DX ottimale, le strutture di risposta e le chiavi che comunicano lo stato devono essere coerenti tra le API. Ad esempio, il campo del codice di errore di cui sopra dovrebbe invariabilmente essere denominato "codice" in ogni API, non "codice" in alcune API e "codice errore" in altre.

Limiti di velocità configurabili

I limiti di velocità determinano l'accessibilità di un'API determinando quante volte un utente può chiamarla in una singola unità di tempo. I limiti di velocità troppo elevati possono inondare i sistemi con un numero ingestibile di richieste che degradano le prestazioni, mentre limiti di velocità irragionevolmente bassi possono causare l'accodamento delle transazioni in sospeso nei sistemi degli utenti. Entrambi contribuiscono alla scarsa DX. Quando si progettano le API, è meglio consentire limiti di tariffa che possono essere modificati in base a casi aziendali e circostanze specifici. I clienti con volumi elevati, ad esempio, potrebbero avere una reale necessità di chiamare le API più frequentemente.

Per determinare al meglio i limiti di frequenza appropriati, è utile prima raggruppare le API in categorie significative in base alla frequenza e al volume con cui vengono chiamate. Ad esempio, le API che configurano i dati primari del cliente (creazione profilo/account) vengono chiamate meno frequentemente e possono gestire limiti tariffari inferiori, mentre le API di transazione ("crea ordine", "invia email") vengono chiamate più frequentemente, richiedendo limiti tariffari più elevati. La definizione di categorie o livelli per diversi casi d'uso rende le API più affidabili e scalabili. Per un esempio di limiti di velocità chiaramente definiti, consulta la documentazione dell'API di Slack.

Documentazione completa

La documentazione funge da manuale utente per un'API. Spiega chiaramente agli sviluppatori cosa fa un'API, come usarla e cosa aspettarsi da essa. Una buona documentazione è scritta in un linguaggio chiaro e accessibile, è dettagliata e interattiva e offre numerose demo e frammenti di codice per semplificare l'integrazione. In questo modo, facilita l'onboarding e un rapido Time to First Hello World (TTFHW), una metrica importante che rappresenta la rapidità con cui uno sviluppatore può chiamare con successo la sua prima API.

La documentazione dovrebbe identificare chiaramente quali campi nella richiesta API sono obbligatori e quali sono facoltativi, nonché la lunghezza minima e massima e il tipo di dati per tali campi. In sostanza, dovrebbe includere tutto il necessario per definire le aspettative e rimuovere gli ostacoli per gli sviluppatori che consumano. Gli sviluppatori che creano schemi di database nei loro sistemi, ad esempio, non dovrebbero dover modificare in seguito la lunghezza delle colonne nelle tabelle perché la documentazione non specifica i parametri.

La documentazione dell'API può aumentare l'adozione non solo fungendo da riferimento affidabile per gli sviluppatori consumatori, ma anche fungendo da strumento di marketing per l'API stessa. Spesso, la prima persona che incontra la documentazione API è uno stakeholder rivolto al business, che la sfoglia durante le fasi iniziali della valutazione del prodotto. Pertanto, non dovrebbe includere solo dettagli sugli elementi tecnici dell'API, ma dovrebbe anche articolare chiaramente i casi d'uso aziendali che l'API rende possibili.

Esistono numerosi strumenti sul mercato che possono aiutare a generare una documentazione API completa. Anche la revisione di esempi di documentazione di alta qualità, come quella di Stripe, è utile.

Unendo tutto

Le integrazioni rappresentano un vasto dominio con molti componenti, ma la comprensione dei principi fondamentali di una buona API è fondamentale per lo sviluppo di una solida strategia. Le API sono molto, molto più di semplici connettori di sistema. Sono gli elementi costitutivi di reti digitali espansive e le chiavi per aprire nuovi flussi di entrate e rilasciare valore non sfruttato. Per questo motivo, una strategia API di successo non riguarda solo la creazione di prodotti; si tratta di costruire potenziale. Un product manager API deve adottare una mentalità della piattaforma e dare la priorità ai fattori che agevoleranno l'adozione per i potenziali partner che possono quindi prendere la loro API, integrarla ed eseguirla.