5 regole d'oro per un'ottima progettazione di API Web

Ti sei mai trovato a chiederti "cosa stavano pensando?" quando si integra un servizio web tramite la sua API? In caso contrario, sei stato molto più fortunato di me.

Qualsiasi sviluppatore di software sa quanto sia facile lasciare che un progetto si trasformi in codice spaghetti e le API Web non sono meno inclini a creare una rete intricata. Ma non è necessario che sia così. In verità, è possibile progettare fantastiche API Web che le persone apprezzeranno davvero l'utilizzo e che ti divertirai anche a creare. Ma come? La risposta a questa domanda è di cosa tratta questo post.

Prospettiva

La maggior parte delle volte quando si creano soluzioni, si progetta per utenti finali che non sono programmatori o che generalmente non sono tecnicamente sofisticati. Stai fornendo loro un'interfaccia grafica e, se hai svolto bene il tuo lavoro, hai raccolto da loro un'idea abbastanza buona di ciò che devono fare l'interfaccia.

Ma lo sviluppo dell'API è diverso. Stai progettando un'interfaccia per i programmatori , probabilmente senza nemmeno sapere chi sono. E chiunque essi siano, avranno la sofisticatezza tecnica (o almeno penseranno di avere la sofisticatezza tecnica) per evidenziare ogni piccolo difetto nel tuo software. È probabile che i tuoi utenti siano critici nei confronti della tua API come tu saresti dei loro e si divertiranno molto a criticarla.

E qui sta parte dell'ironia, tra l'altro. Se qualcuno dovrebbe capire come creare un'API Web facile da usare, sei tu . Dopotutto, sei un ingegnere del software proprio come gli utenti della tua API, quindi condividi il loro punto di vista. tu no?

Bene, anche se certamente capisci il loro punto di vista, non necessariamente condividi il loro punto di vista. Quando sviluppi o migliori la tua API, hai la prospettiva di un designer di API mentre loro hanno la prospettiva di un utente API.

I progettisti di API in genere si concentrano su domande come "Cosa deve fare questo servizio?" o "Cosa deve fornire questo servizio?" , mentre gli utenti dell'API sono concentrati su "Come posso utilizzare questa API per fare ciò di cui ho bisogno?" o, più precisamente, "Come posso dedicare il minimo sforzo per ottenere ciò di cui ho bisogno da questa API?" .

Queste diverse domande portano a due prospettive molto diverse. Di conseguenza, il prerequisito necessario per progettare una grande API è spostare la tua prospettiva da quella del progettista API a quella dell'utente API. In altre parole, poniti continuamente le domande che ti faresti naturalmente se fossi il tuo stesso utente. Invece di pensare a cosa può fare la tua API, pensa ai diversi modi in cui potrebbe aver bisogno o desidera essere utilizzata e quindi concentrati sul rendere queste attività il più semplici possibile per gli utenti della tua API.

Anche se può sembrare facile e ovvio, è sorprendente come raramente le API sembrino essere progettate in questo modo. Pensa alle API che hai incontrato nella tua carriera. Con quale frequenza sembrano essere stati progettati tenendo presente questa prospettiva? La progettazione dell'API Web può essere impegnativa.

Detto questo, procediamo e parliamo delle 5 regole d'oro per la progettazione di una grande API Web , ovvero:

1. Documentazione
2. Stabilità e coerenza
3. Flessibilità
4. Sicurezza
5. Facilità di adozione

Regola 1: Documentazione

Documentazione. Sì, comincio da qui.

Odi la documentazione? Bene, posso entrare in empatia, ma indossa il tuo cappello da "prospettiva utente" e scommetto che l'unica cosa che odi di più del dover scrivere documentazione è dover provare a utilizzare un'API non documentata. Non ho niente da aggiungere.

La linea di fondo è che, se vuoi che qualcuno usi la tua API, la documentazione è essenziale. Devi semplicemente farlo bene. È la prima cosa che vedranno gli utenti, quindi in un certo senso è come la confezione regalo. Presenta bene ed è più probabile che le persone utilizzino la tua API e sopportino qualsiasi idiosincrasia.

Quindi, come scriviamo una buona documentazione?

La parte relativamente facile è documentare i metodi API stessi; cioè, richieste e risposte di esempio, insieme alle descrizioni di ciascuno degli elementi in entrambi. Fortunatamente, esiste un numero crescente di strumenti software che facilitano e semplificano il compito di generare documentazione. Oppure puoi scrivere tu stesso qualcosa che introspezioni la tua API, gli endpoint e le funzioni e generi la documentazione corrispondente per te.

Ma ciò che separa un'ottima documentazione da una documentazione adeguata è l'inclusione di esempi di utilizzo e, idealmente, tutorial. Questo è ciò che aiuta l'utente a comprendere la tua API e da dove iniziare. Li orienta e li aiuta a caricare la tua API nel loro cervello.

Ad esempio, se gli sviluppatori di Twilio dovessero elencare ogni classe, ogni metodo e ogni possibile risposta alla loro API, ma non si preoccupassero di menzionare che puoi inviare un SMS, tracciare una chiamata o acquistare un numero di telefono tramite la loro API, l'utente dell'API impiegherebbe molto tempo per trovare tali informazioni e capirle in modo coerente. Riuscite a immaginare di smistare un gigantesco albero di classi e metodi senza alcuna comprensione di ciò per cui erano usati, a parte il loro nome? Suona terribile vero? Ma questo è esattamente ciò che fanno così tanti provider di API, lasciando così le loro API opache a chiunque tranne che a se stessi. La guida per sviluppatori e API di Rackspace CloudFiles è uno di questi esempi; è difficile orientarsi a meno che tu non capisca già cosa stanno facendo e cosa stanno fornendo.

Quindi scrivi tutorial concisi che aiutino a far funzionare rapidamente lo sviluppatore, con almeno uno scheletro di ciò che stanno cercando di fare, quindi indirizzalo nella direzione dell'elenco di funzionalità più dettagliato e completamente documentato in modo che possano espandersi su quello che hanno.

Una volta che hai finito con la tua documentazione, assicurati di convalidare che ha senso per persone diverse da te. Invialo ad altri sviluppatori nella tua rete, non dare loro istruzioni se non indicando loro la documentazione e chiedi loro di seguire un tutorial o creare qualcosa di veramente semplice in circa 15 minuti. Se non possono avere un'integrazione di base con la tua API in 15 minuti, hai più lavoro da fare.

Per alcuni esempi degni di nota di documentazione eccellente e dettagliata, controlla Twilio, Django e MailChimp. Nessuno di questi prodotti è necessariamente il migliore nei loro mercati (sebbene siano tutti buoni prodotti), tuttavia si distinguono fornendo parte della migliore documentazione all'interno dei loro mercati, il che ha sicuramente facilitato la loro ampia accettazione e quota di mercato.

Regola 2: Stabilità e Coerenza

Se hai mai utilizzato l'API di Facebook, sai quanto spesso deprecano e riscrivono completamente le loro API. Non importa quanto rispetti la loro cultura hacker o il loro prodotto, la loro non è una prospettiva favorevole agli sviluppatori. Il motivo per cui hanno ancora successo è perché hanno un miliardo di utenti, non perché la loro API è eccezionale.

Ma probabilmente non hai il lusso di una base di utenti e una quota di mercato così mastodontiche, quindi avrai bisogno di un'API molto meno volatile, che mantenga le vecchie versioni in esecuzione e supportate per un periodo di tempo piuttosto lungo. Forse anche anni. Quindi, a tal fine, ecco alcuni suggerimenti e trucchi.

Supponiamo, ad esempio, che la tua API sia accessibile tramite l'URL http://myapisite.com/api/widgets e fornisca la sua risposta in formato JSON. Anche se a prima vista può sembrare a posto, cosa succede quando è necessario modificare il formato della risposta JSON? Tutti quelli che sono già integrati con te si romperanno. Ops.

Quindi fai un po' di pianificazione in anticipo e crea la tua API fin dall'inizio, incorporando esplicitamente un numero di versione nell'URL (ad esempio, http://myapisite.com/api/widgets?version=1 o http://myapisite.com/api/widgets/v1 ) in modo che le persone possano fare affidamento sul funzionamento della versione 1 e possono eseguire l'aggiornamento a qualsiasi versione successiva quando sono pronte per farlo. Se a un certo punto devi eliminare gradualmente una versione precedente, vai avanti, ma dai molto preavviso e offri una sorta di piano di transizione.

Un buon schema URL includerà le versioni principali nell'URL. Qualsiasi modifica al formato di output o ai tipi di dati supportati dovrebbe comportare il passaggio a una nuova versione principale. In generale, è accettabile mantenere la stessa versione se tutto ciò che stai facendo è aggiungere chiavi o nodi al tuo output, ma per essere al sicuro, ogni volta che l'output cambia, esegui il bump di una versione.

Oltre a essere stabili nel tempo, le API devono essere internamente coerenti. Ho visto molte API che cambiano i nomi dei parametri o i metodi di POSTing dei dati, a seconda dell'endpoint utilizzato. Dovresti invece gestire parametri comuni a livello globale all'interno della tua API e usare l'ereditarietà o un'architettura condivisa per riutilizzare le stesse convenzioni di denominazione e la stessa gestione dei dati in modo coerente in tutta la tua API.

Infine, devi registrare e pubblicare un log delle modifiche per mostrare le differenze tra le versioni della tua API in modo che gli utenti sappiano esattamente come eseguire l'aggiornamento.

Regola 3: Flessibilità

Garbage in, garbage out (GIGO) è un mantra ben noto alla maggior parte dei programmatori. Applicato alla progettazione di API Web, questo principio guida tende a dettare un approccio abbastanza rigido alla richiesta di convalida. Suona benissimo, vero? Nessun pasticcio, nessun problema.

Eppure, come per ogni cosa, ci deve essere un certo equilibrio. Poiché non è possibile prevedere tutti i modi in cui gli utenti vorranno utilizzare il tuo servizio e poiché non tutte le piattaforme client sono coerenti (ad esempio, non tutte le piattaforme hanno un ottimo supporto JSON, una libreria OAuth decente, ecc.), è bene avere almeno un certo grado di flessibilità o tolleranza per quanto riguarda i propri vincoli di input e output.

Ad esempio, molte API supporteranno una varietà di formati di output, come JSON, YAML, XML, ecc. al., ma supporterà solo la specifica del formato nell'URL stesso. Nello spirito di rimanere flessibile, potresti consentire che questo venga specificato anche nell'URL (ad esempio, /api/v1/widgets.json ), oppure potresti anche leggere e riconoscere un'intestazione HTTP Accept: application/json o supportare un variabile querystring come ?format=JSON e così via.

E già che ci siamo, perché non consentire che il formato specificato non faccia distinzione tra maiuscole e minuscole, in modo che l'utente possa specificare anche ?format=json ? Questo è un classico esempio di un modo per alleviare la frustrazione non necessaria per l'utente della tua API.

Un altro esempio è consentire diversi modi di inserire le variabili. Quindi, proprio come hai una varietà di formati di output, consenti anche una varietà di formati di input (ad esempio, semplici variabili POST, JSON, XML, ecc.). Dovresti almeno supportare le variabili POST standard e molte applicazioni moderne supportano anche JSON, quindi questi due sono un buon punto di partenza.

Il punto qui è che non dovresti presumere che tutti condividano le tue preferenze tecniche. Con una piccola ricerca su come funzionano le altre API e attraverso il dialogo con altri sviluppatori, puoi raccogliere altre valide alternative che sono utili e includerle nella tua API.

Regola 4: Sicurezza

La sicurezza è ovviamente una delle cose più importanti da integrare nel tuo servizio web, ma così tanti sviluppatori lo rendono ridicolmente difficile da usare. In qualità di provider di API, dovresti offrire esempi utilizzabili di come autenticare e autorizzare quando accedi alla tua API. Questo non dovrebbe essere un problema difficile su cui un utente finale trascorre ore a lavorare. Rendi il tuo obiettivo che non debbano scrivere alcun codice o impiegano meno di 5 minuti per scriverlo.

Per la maggior parte delle API, preferisco una semplice autenticazione basata su token, in cui il token è un hash casuale assegnato all'utente e può ripristinarlo in qualsiasi momento se è stato rubato. Consenti il ​​passaggio del token tramite POST o un'intestazione HTTP. Ad esempio, l'utente potrebbe (e dovrebbe) inviare un token SHA-1 come variabile POST o come intestazione in un formato come "Autorizzazione: da39a3ee5e6b4b0d3255bfef95601890afd80709".

Inoltre, scegli un token sicuro, non un identificatore numerico breve. Qualcosa di irreversibile è meglio. Ad esempio, è relativamente semplice generare un token SHA durante la creazione dell'utente e archiviarlo nel database. Quindi, puoi semplicemente interrogare il tuo database per tutti gli utenti che corrispondono a quel token. Potresti anche creare un token generato con un identificatore univoco e un valore salt, qualcosa come SHA(User.ID + "abcd123") , e quindi eseguire una query per qualsiasi utente che corrisponda; ad esempio, where TokenFromPost = SHA(User.ID + "abcd123") .

Un'altra opzione molto buona è OAuth 2 + SSL. Dovresti comunque utilizzare SSL, ma OAuth 2 è ragionevolmente semplice da implementare sul lato server e le librerie sono disponibili per molti linguaggi di programmazione comuni.

Se l'API che hai creato dovrebbe essere accessibile su un sito Web pubblico tramite JavaScript, devi anche assicurarti di convalidare un elenco di URL per account per il token. In questo modo, nessuno può andare a ispezionare le chiamate alla tua API, rubare il token dal tuo utente e usarlo per se stesso.

Ecco alcune altre cose importanti da tenere a mente:

• Funzionalità di whitelist. Le API generalmente consentono di eseguire operazioni di base di creazione, lettura, aggiornamento ed eliminazione sui dati. Ma non vuoi consentire queste operazioni per ogni entità, quindi assicurati che ciascuna disponga di una whitelist di azioni consentite. Assicurati, ad esempio, che solo gli utenti autorizzati possano eseguire comandi come /user/delete/<id> . Allo stesso modo, anche tutte le intestazioni utili inviate nella richiesta dell'utente devono essere convalidate rispetto a una whitelist. Se consenti le intestazioni di tipo di contenuto, verifica che qualsiasi cosa l'utente invia corrisponda effettivamente a un elenco di tipi di contenuto supportati. In caso contrario, inviare un messaggio di errore come una risposta 406 non accettabile. La whitelist è importante in quanto molte API vengono generate automaticamente o utilizzano invece una blacklist, il che significa che devi essere esplicito su ciò che non vuoi. Tuttavia, la regola d'oro della sicurezza è iniziare con assolutamente nulla e consentire solo esplicitamente ciò che si desidera.

• Proteggiti dalla falsificazione delle richieste tra siti (CSRF). Se si consente l'autenticazione della sessione o dei cookie, è necessario assicurarsi di proteggersi dagli attacchi CSRF. L'Open Web Application Security Project (OWASP) fornisce indicazioni utili sui modi per escludere queste vulnerabilità.

• Convalida l'accesso alle risorse. In ogni richiesta, è necessario verificare che a un utente sia effettivamente consentito l'accesso all'elemento specifico a cui fa riferimento. Pertanto, se si dispone di un endpoint per visualizzare i dettagli della carta di credito di un utente (ad es. /account/card/view/152423 ), assicurarsi che l'ID "152423" faccia riferimento a una risorsa a cui l'utente è effettivamente autorizzato ad accedere.

• Convalida tutti gli input. Tutto l'input di un utente deve essere analizzato in modo sicuro, preferibilmente utilizzando una libreria nota se si utilizza un input complicato come XML o JSON. Non costruire il tuo parser, o ti aspetta un mondo di dolore.

Regola 5: Facilità di adozione

Questa è davvero la regola più importante del gruppo e si basa su tutte le altre. Come ho detto durante la regola di documentazione, provalo con persone che non conoscono la tua API. Assicurati che possano essere operativi con almeno un'implementazione di base della tua API, anche se sta solo seguendo un tutorial, in pochi minuti. Penso che 15 minuti siano un buon obiettivo.

Ecco alcuni consigli specifici per facilitare e facilitare l'adozione della tua API:

• Assicurati che le persone possano effettivamente utilizzare la tua API e che funzioni la prima volta, ogni volta. Chiedi a nuove persone di provare occasionalmente a implementare la tua API per verificare che non crei confusione in qualche modo da cui sei diventato immune.

• Mantieni la semplicità. Non eseguire alcuna autenticazione di fantasia. Non fare uno schema di URL personalizzato pazzo. Non reinventare SOAP, o JSON, o REST o altro. Usa tutti gli strumenti che puoi che sono già stati implementati e sono ampiamente accettati, in modo che gli sviluppatori debbano solo imparare la tua API, non la tua API + 10 nuove tecnologie oscure.

• Fornisci librerie specifiche della lingua per interfacciarsi con il tuo servizio. Ci sono alcuni strumenti utili per generare automaticamente una libreria per te, come Alpaca o Apache Thrift. Attualmente Alpaca supporta Node, PHP, Python e Ruby. Thrift supporta C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi e altri.

• Semplifica qualsiasi registrazione necessaria. Se non stai sviluppando un'API open source o se esiste un processo di registrazione di qualsiasi tipo, assicurati che al momento della registrazione, un utente venga indirizzato molto rapidamente a un tutorial. E rendi il processo di registrazione completamente automatizzato senza alcuna necessità di interazione umana da parte tua.

• Fornisci un supporto eccellente. Un grosso ostacolo all'adozione è la mancanza di supporto. Come gestirai e risponderai a una segnalazione di bug? E la documentazione poco chiara? Un utente non sofisticato? Forum, bug tracker e supporto e-mail sono fantastici inizi, ma assicurati che quando qualcuno pubblica un bug, lo risolvi davvero. Nessuno vuole vedere un forum di una città fantasma o un enorme elenco di bug che non sono stati risolti.

Riepilogo API Web

I servizi Web e le relative API abbondano. Sfortunatamente, la stragrande maggioranza è difficile da usare. I motivi vanno da una progettazione scadente, alla mancanza di documentazione, alla volatilità, a bug irrisolti o, in alcuni casi, a tutto quanto sopra.

Seguire le indicazioni in questo post ti aiuterà a garantire che la tua API web sia pulita, ben documentata e facile da usare. Tali API sono davvero rare ed è quindi molto più probabile che vengano ampiamente adottate e utilizzate.