Comprensione delle piattaforme basate su API: una guida per i product manager

Costruire un prodotto digitale oggi significa integrare la miriade di vari sistemi di back-office con i punti di contatto e i dispositivi dei clienti. Il costo del coinvolgimento di un team software per connetterli in un'unica soluzione funzionante potrebbe salire alle stelle.

Questo è il motivo per cui i product manager moderni, quando scelgono i fornitori, spesso mettono al primo posto le capacità di integrazione che possono dipendere dalla scelta dei sistemi che espongono le API. Che cos'è l'API e come testarla senza coinvolgere il tuo team tecnico? Continuare a leggere.

Abbraccia i dati: perché abbiamo bisogno delle API

I dati dei clienti cambiano il modo in cui opera l'azienda. Se opportunamente raccolti e spostati, possono aiutare le aziende ad aumentare i tassi di acquisizione e fidelizzazione dei clienti, portando alla fine a un aumento delle entrate.

Ma il crunching dei dati è un lavoro noioso. Ecco perché il business ha attinto all'informatica. Negli anni '90, i database che automatizzavano le attività di dati più dispendiose in termini di tempo sono diventati estremamente popolari nei dipartimenti di marketing. Ciò ha portato a un enorme cambiamento nel modo in cui sono state concepite le strategie di marketing: quel cambiamento è stato chiamato approccio basato sui dati .

I database hanno avuto un grosso problema, però. Per renderli qualcosa di prezioso, un'azienda aveva bisogno di assumere ingegneri del software. Erano gli eroi che sapevano come trasformare enormi pile di dati in intuizioni funzionanti. Erano anche le guardie che proteggevano l'integrità dei dati e quindi assicuravano che il sistema fosse a prova di futuro.

Ma gli ingegneri del software costano molto e la loro interfaccia di comunicazione richiedeva uno sforzo.

Quando il numero di canali di raccolta dei dati si estendeva su più dipartimenti e persino su società esterne, i database e i loro operatori sono diventati un collo di bottiglia. Le aziende dovevano trovare un modo automatizzato per accedere agli archivi dati.

È così che è nata l'idea dei sistemi API-first.

Che cos'è effettivamente l'API senza il gergo tecnico

I sistemi API-first, oggi comunemente abbreviati in API ( A pplication P rogrammable Interface), sono le applicazioni che assicurano che altri sistemi possano accedere ai propri dati in modo unificato e sicuro.

Senza un grado di informatica, l' interfaccia programmabile dell'applicazione non suona davvero un campanello. Diamo un'occhiata a una spiegazione più tangibile.

Una delle migliori analogie che ho trovato finora nel web è stata scritta da Taija:

“Se vai in un ristorante come cliente, non ti è permesso entrare in cucina. Devi sapere cosa è disponibile. Per questo, hai il menu. Dopo aver visto il menu, fai un ordine a un cameriere, che lo passa in cucina e che poi consegnerà ciò che hai chiesto. Il cameriere può consegnare solo ciò che la cucina può fornire.

La migliore analogia con l'API che ho visto: prendi un ristorante. Il menu è l'API, il tuo ordine è la chiamata API, il cibo della cucina è la risposta.

— Aarthi 發財! (@AarthiD) 19. Dicembre 2013

Come si collega a un'API? Il cameriere è l'API. Sei una persona che chiede servizio. In altre parole, sei un cliente o consumatore API. Il menu è la documentazione che spiega cosa puoi chiedere all'API. La cucina è, ad esempio, un server; un database che contiene solo un certo tipo di dati: tutto ciò che l'acquirente ha acquistato per il ristorante come ingredienti e ciò che lo chef ha deciso che offriranno e ciò che i cuochi sanno come preparare".

Quindi ancora:

• Cucina
  Il database, nessun cliente autorizzato a proteggere l'integrità dei dati.
• Cameriere
  L'API, un intermediario che sa come servire i dati dal database senza interromperne il funzionamento.
• Cliente
  Un sistema esterno che vuole ottenere i propri dati
• Menù
  Il formato dei dati fa riferimento ai sistemi esterni che devono utilizzare per eseguire le proprie operazioni.
• Ordine
  Una vera e propria chiamata API singola.

Allo stato attuale della tecnologia, è ancora necessario uno sviluppatore di software per "fare un ordine". Ma è molto più veloce (leggi: più economico) perché il menu, come McDonald's, è più o meno standardizzato in tutto il mondo.

Quindi ora indosseremo i panni di uno sviluppatore di software e proveremo a chiamare un'API esemplare. Non preoccuparti; non andremo oltre le lezioni di informatica scolastica.

Come la tua app meteo ottiene i dati: nozioni di base sulle API

Scopriremo come la tua app meteo conosce la temperatura attuale. In questo modo, otterremo le nozioni di base su come comunicare con i sistemi su Internet.

Ciò che ci serve:

• Un database meteo
• Un browser
• Un pizzico di forza di volontà

Questo è tutto! La tecnologia odierna semplifica il test dell'API senza la necessità di grandi strumenti di sviluppo.

Naturalmente, è diverso quando si desidera creare un'integrazione completa. Quando arriva il momento critico, devi conoscere strumenti e linguaggi di programmazione più avanzati, ma per test/prova di concetti, questa configurazione è sufficiente.

Quindi, proviamo a ottenere l'indice di temperatura corrente per la tua città o, nel gergo dei programmatori, invochiamo la prima chiamata API. Dopotutto, si tratta di inviare del testo a un server e ricevere un messaggio in cambio .

L'anatomia di una richiesta API

In questo articolo utilizzeremo l'API https://openweathermap.org. Visita il sito e prova a controllare le condizioni meteorologiche in diverse località. Spero che tu ti senta meglio di me a Katowice oggi:

Come avrai intuito, il sito Web sta chiamando l'API per ottenere i dati. Gli sviluppatori l'hanno implementato in modo tale che ogni volta che si preme il tasto cerca , dietro le quinte l'applicazione bussa alla porta dell'API e dice "dammi la temperatura <città>".

Indossiamo un cappello da hacker e vediamo le chiamate API che questo sito Web sta chiamando con il tuo browser. Puoi utilizzare gli Strumenti per sviluppatori nel tuo browser per vedere cosa sta succedendo dietro le quinte:

1. In Chrome, vai su Menu → Altri strumenti → Strumenti per sviluppatori;
2. Passa alla scheda Rete;
3. Prova a controllare la temperatura in diverse città nel widget sopra;
4. Nell'elenco in basso, noterai i collegamenti che sono stati chiamati:
   

   

   
   Se copi il link, puoi vedere che include il nome della posizione e un paio di altri parametri.
   

    https://openweathermap.org/data/2.5/find?callback=jQuery19103887954878001505_1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

5. Quando incolli il link nella barra degli indirizzi del browser, dovresti vedere le risposte dell'API con:
   

    jQuery19103887954878001505_1542285819413({"message":"accurate","cod":"200","count":1,"list":[{"id":3096472,"name":"Katowice","coord":{"lat":50.2599,"lon":19.0216},"main":{"temp":281.69,"pressure":1031,"humidity":61,"temp_min":281.15,"temp_max":282.15},"dt":1542285000,"wind":{"speed":3.6,"deg":50},"sys":{"country":"PL"},"rain":null,"snow":null,"clouds":{"all":90},"weather":[{"id":804,"main":"Clouds","description":"overcast clouds","icon":"04d"}]}]})

6. È un po' caotico, ma se elimini il contenuto delle parentesi e lo esegui con un formattatore di dati, vedrai una struttura che ha senso:
   

    { "message":"accurate", "cod":"200", "count":1, "list":[ { "id":3096472, "name":"Katowice", "coord":{ "lat":50.2599, "lon":19.0216 }, "main":{ "temp":281.69, "pressure":1031, "humidity":61, "temp_min":281.15, "temp_max":282.15 }, "dt":1542285000, "wind":{ "speed":3.6, "deg":50 }, "sys":{ "country":"PL" }, "rain":null, "snow":null, "clouds":{ "all":90 },

7. La risposta dell'API è una struttura di dati con informazioni sulle condizioni meteorologiche attuali: dovresti decrittografare facilmente la maggior parte dei parametri. Questo formato di dati è chiamato JSON . Questa è una notazione importante perché la maggior parte delle API moderne la usa. Questa pila di ident e parentesi ha uno scopo: è più facile per un'applicazione analizzare un messaggio ben strutturato rispetto a un testo posizionato a caso.

Una parola di spiegazione di ciò che abbiamo appena fatto qui.

L'applicazione Web dietro il sito Web di Open Weather Map prende i dati dall'API e li visualizza sul sito Web.

Ogni volta che si digita il nome della città e si preme cerca , il sito si collega ad un server con un link specifico che include come parametro il nome della città.

La stessa frase in gergo tecnico: l'applicazione dietro il sito invia una richiesta a un endpoint API fornendo come argomento il nome della città.

Quindi, l'API risponde (invia una risposta API ) con un messaggio di testo formattato come JSON .

Per creare una richiesta API devi mettere insieme il suo indirizzo. Sì, l'indirizzo è una buona analogia. Per spedire qualcosa è necessario fornire al corriere:

• Città,
• Via e numero,
• A volte qualche informazione in più su come raggiungere il tuo ufficio.

E, per connettersi all'API, per analogia, è necessario:

• https://openweathermap.org/ (link) La città o il root-endpoint — un punto di partenza, un indirizzo Internet di un server a cui ci si vuole connettere, nel nostro caso.
• data/2.5/find (link) Il numero civico o il percorso — determina la risorsa che si desidera ottenere da un'API.
• ?callback=jQuery19103887954878001505 1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22& =1542285819418 (link) Le informazioni extra o i parametri della query - lascia che l'API

Ecco come vengono progettate le API. L'endpoint radice di solito rimane lo stesso per un singolo fornitore, quindi è necessario capire quali parametri di percorso e query sono disponibili e quali informazioni il team di sviluppo dell'API ha inserito dietro di essi.

Ora mettiamo un po' più stretto il cappello da hacker. Nel nostro caso, non tutti i parametri di query sono necessari per ottenere i dati meteorologici. Prova a rimuovere parametri diversi dopo il punto interrogativo ( ? ) e controlla come risponde l'API Weather.

Ad esempio, puoi iniziare rimuovendo la callback dal link della richiesta:

 https://openweathermap.org/data/2.5/find?callback=jQuery19103887954878001505_1542285819413&q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

Il risultato:

 https://openweathermap.org/data/2.5/find?q=Katowice&type=like&sort=population&cnt=30&appid=b6907d289e10d714a6e88b30761fae22&_=1542285819418

Se giochi con gli altri, puoi vedere che anche alcuni di essi sono opzionali. In realtà solo q e appid sono obbligatori:

 https://openweathermap.org/data/2.5/find?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

Come fai a sapere cosa è obbligatorio e cosa è opzionale? Come fai a sapere dove ottenere l'endpoint radice e il percorso in primo luogo?

Documentazione API: da leggere prima di iniziare

Devi sempre controllare prima la documentazione dell'API per imparare a costruire la tua richiesta nel modo giusto.

Nel nostro caso, la documentazione https://openweathermap.org/current mostra gli endpoint disponibili. Spiega anche tutti i campi dei dati di risposta, così puoi trovare quali informazioni risponderà l'API anche prima ancora di inviare una richiesta.

Una buona documentazione API offre tutorial di avvio rapido su come creare richieste semplici e passa a cose più avanzate. Fortunatamente, l'API Open Weather ne ha una e la useremo ora.

Creazione di una chiamata API da zero

Riassumiamo i nostri risultati. Abbiamo già inviato una richiesta all'API. Abbiamo individuato il collegamento corretto annusando ciò che OpenWeatherMap fa dietro le quinte. Questo approccio è chiamato reverse engineering e spesso è difficile o non è affatto possibile.

Inoltre, il più delle volte, i fornitori di API vietano agli utenti di utilizzare eccessivamente questa opzione. Ecco perché dovremmo imparare a "chiamare" l'API secondo le regole (che significa: documentazione).

Un modo per farlo è codificarlo. Ma poiché non siamo programmatori ( ancora! ), useremo strumenti che lo rendono più facile. Tanto più facile che anche gli sviluppatori di software lo hanno sotto la loro cintura degli strumenti.

Come promesso, non lasceremo il browser. Ma dobbiamo installare un'estensione (solo Chrome) — Postman. Questo semplice plugin trasforma il tuo browser in un connettore API.

OK, ora che abbiamo uno strumento, diamo un'occhiata alla documentazione per vedere come possiamo ottenere le condizioni meteorologiche attuali per un nome di città specifico https://openweathermap.org/current#name .

I documenti dicono che dovremmo usare il seguente endpoint: api.openweathermap.org/data/2.5/weather?q={city name}

Quando lo scomponiamo otteniamo i seguenti elementi:

• Root-endpoint: api.openweathermap.org
• Percorso: data/2.5/weather
• Parametro di query: q={city name} (questa nozione significa che dovremmo sostituire le parentesi graffe con un nome di città specifico)

Mettiamolo in postino. Il processo si riduce a tre semplici passaggi:

1. Fare clic su "Richiesta" nel menu in alto.
   

   

2. Assegna un nome alla tua richiesta e fornisci anche il nome del catalogo nella sezione in basso.

   

3. Incolla l'endpoint API che desideri chiamare, fai clic su Invia e dovresti vedere la risposta API nella sezione Risposta:

   

Congratulazioni! Hai appena chiamato con successo il tuo abete... aspetta un secondo! Prestiamo attenzione alla risposta dell'API:

Non è un JSON pieno di informazioni meteorologiche che abbiamo visto prima. Cosa significano la chiave API 401 e non valida? La nostra documentazione è sbagliata?

Autenticazione

Non permetteresti a nessuno di accedere al tuo armadietto dei cocktail senza il tuo permesso, vero? Allo stesso modo, i provider di API vogliono anche controllare gli utenti del loro prodotto per proteggerlo da attività dannose. Cos'è l'attività dannosa? Ad esempio, l'invio di molte richieste API contemporaneamente, che "surriscalda" il server e causa tempi di inattività per altri utenti.

Come puoi controllare l'accesso? Allo stesso modo in cui proteggi i tuoi drink! Usando le chiavi — Chiavi API .

Se visiti la guida Come iniziare dalla documentazione dell'API Weather, noterai come ottenere la tua chiave. Iscriviti ora e controlla la tua casella di posta.

Quindi ora la domanda è come usare la chiave? È facile, secondo i documenti, basta copiare e incollare la chiave alla fine dell'URL dell'endpoint (senza parentesi).

 api.openweathermap.org/data/2.5/weather?q=Katowice&appid={your API key}

E fai di nuovo clic su Invia. Ecco qua, ora possiamo vedere la risposta dell'API!

Ma c'è molto di più che puoi ottenere dall'API usando Postman. Pronto a diventare un vero hacker API?

Parametri API: ottenere risposte personalizzate

Di solito, gli endpoint API hanno alcune funzioni di utilità che puoi utilizzare per regolare la risposta API, ad esempio se hai bisogno di un formato dati migliore o se vuoi ottenere i dati in un ordine particolare. Queste opzioni sono spesso nascoste dietro alcuni parametri che puoi trovare nella documentazione.

I parametri della query sono solo un testo strutturato che aggiungi all'indirizzo dell'endpoint con il seguente schema:

1. Un punto interrogativo ( ? ) dopo il percorso,
2. Nome di un parametro,
3. È uguale a ( = ) simbolo,
4. Valore del parametro,
5. E commerciale ( & ) e altri seguono con i punti 2-4 (in questo modo puoi aggiungere tutti i parametri che vuoi).

Prendi come esempio la nostra prima richiesta:

 https://openweathermap.org/data/2.5/find?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

Nota importante: l'ordine dei parametri della query non ha importanza.

 ?q=Katowice&appid=b6907d289e10d714a6e88b30761fae22

Quanto sopra è uguale al seguente:

 ?appid=b6907d289e10d714a6e88b30761fae22&q=Katowice

Come accennato, i parametri di query sono descritti nei documenti API. Il seguente estratto dalla documentazione dell'API meteo mostra come ottenere la temperatura in diverse unità (imperiali o metriche):

Prova a inviare queste due opzioni con Postman per vedere la differenza nei risultati. Ricorda di aggiungere la tua chiave API alla fine dell'indirizzo dell'endpoint.

Nota : prenditi sempre del tempo per studiare la documentazione e trovare parametri che possono far risparmiare a te o al tuo team di sviluppo un bel po' di tempo.

Opzioni di richiesta API: come inviare dati all'API

Finora abbiamo ricevuto informazioni dall'API. Cosa succede se vogliamo aggiungere o modificare informazioni nel database dietro l'API? I metodi di richiesta sono la risposta.

Diamo un'occhiata al postino ancora una volta. Potresti aver notato un'etichetta GET maiuscola accanto all'indirizzo dell'endpoint API. Questo rappresenta uno dei quattro metodi di richiesta. GET significa che vogliamo ottenere qualcosa dall'API (grazie al capitano) ed è un'opzione predefinita. Quali sono le altre opzioni?

Ancora confuso? Passiamo agli esempi.

API POST: come creare un record nell'API

Non possiamo creare o aggiornare nulla con l'API Weather (perché è pensata per essere di sola lettura), quindi dobbiamo trovarne una diversa a scopo di test.

Facciamo qualche esempio più orientato al business. Simuleremo il seguente scenario:

Se piove, crea un buono sconto "tira su" per i tuoi clienti.

Utilizzeremo Voucherify che fornisce un'API per la creazione e il monitoraggio delle promozioni per qualsiasi sistema di e-commerce.

Disclaimer : sono un co-fondatore di Voucherify. Sono felice di rispondere alle tue domande sulla progettazione e l'implementazione di promozioni digitali e ovviamente sulla nostra API .

Sappiamo già come ottenerli dall'esempio precedente, quindi concentriamoci sulla creazione di un voucher:

1. Come abbiamo detto, dovremmo sempre iniziare con la documentazione.
2. La guida di avvio rapido ci dice di ottenere la nostra chiave API.
   Nota : invece di creare un account, puoi utilizzare i tasti di prova della guida di avvio rapido: ti mostreremo come tra un minuto.
3. Ora, scopriamo come creare un buono sconto. In Voucherify, questo tipo di promozione è rappresentato come “voucher”.
4. Dai documenti imparerai che per creare un voucher, devi chiamare un metodo POST all'endpoint /vouchers .
5. Crea una nuova richiesta in Postman.
6. Cambia metodo in POST.
   

   

7. Incolla l'endpoint Voucherify https://api.voucherify.io/v1/vouchers/ e fai clic su Invia.
   

   

8. Oh schiocco, non siamo autorizzati a chiamare questo endpoint. Come avrai intuito, dobbiamo fornire chiavi API.
   
   Voucherify ha un modo leggermente diverso per farlo. Invece di inserirli come parametri di query, dovresti inserirli in Intestazioni. Questo è un approccio comune perché è più facile implementare e gestire le chiavi in ​​questo modo piuttosto che aggiungerle come parametri di query.
   
   Aggiungi le chiavi come nell'immagine e fai clic su Invia. Si noti che Voucherify richiede due chiavi. Ecco quelli che puoi usare ai fini di questo tutorial:
   X-App-Id: 8a824b12-0530-4ef4-9479-d9e9b9930176 X-App-Token: 9e322bac-8297-49f7-94c8-07946724bcbc

   

9. Riceviamo un altro messaggio di errore, questa volta dice che il carico utile non può essere vuoto.
   

   

   
   Che diavolo è un carico utile? Come nel caso di GET vogliamo recuperare alcune informazioni, con POST dobbiamo inviare qualcosa e il messaggio che inviamo si chiama payload e di solito è un file JSON.
   
   Ora Voucherify API si lamenta del fatto che non ne abbiamo fornito uno, il che significa che non può creare un voucher perché non abbiamo detto che tipo di voucher dovrebbe creare. Così quello che ora? Torna ai documenti!
10. Scopriamo di che tipo di informazioni ha bisogno questa richiesta per avere successo. Possiamo vedere molte opzioni nell'elenco.
    

    

    
    Un parametro (tipo) è obbligatorio e un altro facoltativo. Diciamo che sarà uno sconto del 20%, disponibile per i primi 100 clienti, con scadenza oggi. Ora dobbiamo trovare i parametri responsabili di queste funzionalità di sconto e metterli insieme in un formato non stabile per Voucherify API. Come puoi vedere negli esempi sopra, la notazione JSON che dovresti usare è simile a questa:

     { "type":"DISCOUNT_VOUCHER", "discount":{ "percent_off":20.0, "type":"PERCENT" }, "expiration_date":"2018-12-03T23:59:59Z", "redemption":{ "quantity":100 }

11. Per impostare il payload in Postman, incolla il messaggio JSON nella scheda Corpo. Seleziona il tipo "raw" e JSON dall'elenco dei formati di payload disponibili e conferma con Invia.
    

    

12. Ecco! Voucherify ha creato con successo il nostro buono sconto del 20% (dato che stiamo lavorando con un account di prova, tutti i codici generati iniziano con il prefisso "voucherify.io-"). Il team di marketing può ora condividere il codice con i clienti e Voucherify lo convaliderà automaticamente ogni volta che si recheranno nel tuo negozio per riscattarlo.
    

    

    
    Ma come facciamo a sapere che è una richiesta di successo? Prima di tutto, possiamo vedere che Voucherify ci ha inviato un messaggio che, secondo i loro documenti, sembra una risposta API corretta. In secondo luogo, Postman mostra lo stato 200 OK , il che significa che la nostra richiesta è andata a buon fine. Perché 200 e qual è lo stato?

Codici di stato API e messaggi di errore

La maggior parte delle API con cui interagirai mai sarà basata su HTTP. HTTP è un protocollo che standardizza la comunicazione tra varie applicazioni client e server su Internet.

Uno degli elementi chiave di HTTP sono i codici di stato. Comprendendo il codice di stato tu (o effettivamente i sistemi che implementi) puoi dire immediatamente cosa è successo alla tua richiesta. È probabile che tu abbia affrontato uno dei codici di stato più popolari quando hai digitato il collegamento sbagliato: 404

Ma ce ne sono molti di più e gli utenti finali di solito non li vedono. Vanno da 100+ a 500+. In generale, i numeri seguono le seguenti regole:

• 200+ significa che la richiesta è andata a buon fine;
• 300+ significa che la richiesta viene reindirizzata a un altro URL;
• 400+ significa che si è verificato un errore che ha origine dall'applicazione client;
• 500+ significa che si è verificato un errore che ha origine dal server.

Se potessi ripetere i passaggi ancora una volta, vedresti che Voucherify ha risposto con 401 Non autorizzato quando non abbiamo fornito le chiavi API. Oppure 400 richieste non valide quando non c'era payload richiesto per la richiesta Crea voucher. Infine, abbiamo ricevuto 200 come token di una chiamata API riuscita.

Se sei curioso del significato dei codici di stato HTTP, non c'è posto migliore di HTTP Cats (o forse questo articolo).

Sommario

La crescente quantità di dati e la necessità di velocità nella creazione dei prodotti hanno spinto le API a diventare la lingua franca dei team digitali. Per progettare sistemi basati su sistemi API first, assicurati di comprendere le offerte dei fornitori. Questa guida pratica ai test è un buon punto di partenza per farlo. Ti aiuterà a esplorare le funzionalità dell'API prima ancora di lanciarle al tuo team di insegnanti, risparmiando la loro energia e anche la tua.

Ulteriori letture

• "Un'introduzione alle API di e-commerce per i non sviluppatori", Scott Brinker
• "Vai oltre il CMS senza testa: incontra il commercio senza testa", Michal Sedzielewski, Voucherify
• "Come utilizzare le prime piattaforme API per creare i tuoi siti Web più velocemente", Michal Sedzielewski, Medium
• "Come utilizzare la tua prima piattaforma API per preparare il tuo prototipo per la produzione", Michal Sedzielewski, Medium
• "Come utilizzare il cloud per creare applicazioni più velocemente", Michal Sedzielewski, Hacker Noon