Ricerca nel sito web

4 caratteristiche essenziali delle API di successo


Un'API deve fare molto di più che "semplicemente funzionare".

Se stai creando un'applicazione che utilizza qualche variazione del modello client/server, hai bisogno di un'interfaccia di programmazione dell'applicazione (API). Un'API è un confine chiaramente definito tra un processo e l'altro. Un limite comune nelle applicazioni Web è un'API REST/JSON.

Sebbene gli sviluppatori possano concentrarsi principalmente sul funzionamento (o sulla funzione) dell'API, ci sono alcuni requisiti "non funzionali" che richiedono la loro attenzione. I quattro requisiti non funzionali indispensabili per tutte le API sono:

  • Sicurezza
  • Documentazione
  • Validazione
  • Test

Sicurezza

La sicurezza è un requisito essenziale nello sviluppo del software. Ci sono quattro aree che gli sviluppatori API devono includere in merito alla sicurezza:

  1. Certificati HTTPS/SSL
  2. Condivisione di risorse multiorigine
  3. Autenticazione e token Web JSON
  4. Autorizzazioni e ambiti

1. Certificati HTTPS/SSL

Lo standard di riferimento per il Web è HTTPS che utilizza i certificati SSL e Let's Encrypt può aiutarti a raggiungere questo obiettivo. Si tratta di un'autorità di certificazione gratuita, automatizzata e aperta dell'Internet Security Research Group (ISRG) senza scopo di lucro.

Il software Let's Encrypt genera certificati dell'autorità centrale per il tuo dominio. Questi certificati garantiscono che i payload dei dati dalla tua API al client siano crittografati da un punto all'altro.

Let's Encrypt supporta diverse opzioni di distribuzione per la gestione dei certificati; consulta la sua documentazione per trovare la soluzione giusta per le tue esigenze.

2. Condivisione di risorse tra origini

CORS è un controllo preliminare della politica di sicurezza specifica del browser. Se il tuo server API non si trova nello stesso dominio del dominio del cliente richiedente, dovrai occuparti di CORS. Ad esempio, se il tuo server è in esecuzione su api.domain-a.com e riceve una richiesta client da domain-b.com, CORS invia una richiesta di precontrollo HTTP per vedere se il tuo servizio API accetterà richieste lato client dal dominio del cliente.

Secondo MDN:

"La condivisione delle risorse tra origini (CORS) è un meccanismo basato su intestazione HTTP che consente a un server di indicare qualsiasi altra origine (dominio, schema o porta) diversa dalla propria da cui un browser dovrebbe consentire il caricamento delle risorse."

(Documenti web MDN, CC-BY-SA 2.5)

Esistono molte librerie di supporto per Node.js per aiutare gli sviluppatori API con CORS.

3. Autenticazione e token Web JSON

Esistono diversi approcci per convalidare un utente autenticato nella tua API, ma uno dei modi migliori è utilizzare JSON Web Token (JWT). Questi token sono firmati utilizzando vari tipi di librerie crittografiche note.

Quando un client accede, un servizio di gestione delle identità fornisce al client un JWT. Il client può quindi utilizzare questo token per effettuare richieste all'API. L'API ha accesso a una chiave pubblica o a un segreto che utilizza per verificare il token.

Sono disponibili diverse librerie per facilitare la verifica dei token, incluso jsonwebtoken. Per ulteriori informazioni su JWT e sulle librerie che lo supportano in ogni lingua, controlla JWT.io. 

import jwt from 'jsonwebtoken'

export default function (req, res, next) {
    // req.headers.authorization Bearer token
    const token = extractToken(req)
    jwt.verify(token, SECRET, { algorithms: ['HS256'] }, (err, decoded) => {
	if (err) { next(err) }
	req.session = decoded
	next()
    })
}

4. Autorizzazioni e ambiti

L'autenticazione (o la verifica dell'identità) è importante, ma lo è anche l'autorizzazione, ovvero il client verificato ha il privilegio di eseguire questa richiesta? È qui che gli ambito sono preziosi. Quando il client esegue l'autenticazione con il server di gestione delle identità e viene creato un token JWT, il fatto che il servizio di gestione delle identità fornisca gli ambiti per un determinato client autenticato può consentire al servizio API di determinare se questa richiesta del client verificato può essere eseguita senza dover eseguire un'ulteriore ricerca costosa di un elenco di controllo degli accessi.

Un ambito è un blocco di testo (solitamente delimitato da spazi) che descrive la capacità di accesso di un endpoint API. Normalmente, gli ambiti sono suddivisi tra Risorse e Azioni. Questo modello funziona bene per le API REST/JSON poiché sono strutturate in modo molto simile in un formato RESOURCE:ACTION (ad esempio, ARTICLE:WRITE o ARTICLE:READ, dove ARTICLE è la risorsa e READ e WRITE sono le azioni).

Ciò consente all'API di concentrarsi sulla funzione e non sui ruoli o sugli utenti. Il servizio di gestione dell'accesso alle identità può correlare ruoli e utenti agli ambiti, quindi fornire gli ambiti al client in un JWT verificato.

Riepilogo

Quando si creano e distribuiscono API, la sicurezza dovrebbe sempre essere uno dei requisiti più importanti. Sebbene la sicurezza sia un argomento ampio, affrontare queste quattro aree posizionerà bene la tua API per gli ambienti di produzione.

Documentazione

Cosa c'è di peggio di nessuna documentazione? Documentazione obsoleta.

Gli sviluppatori hanno un rapporto di amore-odio con la documentazione. Tuttavia, la documentazione è una parte cruciale della definizione di successo di un'API. Gli sviluppatori devono sapere come utilizzare l'API e la documentazione creata svolge un ruolo enorme nell'educare gli sviluppatori su come utilizzarla al meglio.

Ci sono tre aree su cui concentrarsi nella documentazione API:

  1. Onboarding degli sviluppatori (README)
  2. Riferimento tecnico (Specifiche)
  3. Utilizzo (Guida introduttiva e altre guide)

1. Onboarding degli sviluppatori

Quando crei un servizio API, devi specificare cose come: cosa fa l'API? Come si configura un ambiente di sviluppo? Come testare il servizio? Come si invia un problema? Come lo distribuisci?

Il modo usuale per rispondere a queste domande è con un file README. È il file nel repository del codice che offre agli sviluppatori un punto di partenza per lavorare con il tuo progetto.

Un README dovrebbe contenere:

  • Una descrizione dell'API
  • Collegamenti a riferimenti tecnici e guide
  • Come impostare il progetto come sviluppatore
  • Come testare il progetto
  • Come implementare il progetto
  • Gestione delle dipendenze
  • Guida al contributo
  • Codice di comportamento
  • Licenza
  • Gratitudine

Sii conciso nel tuo README; non devi spiegare ogni aspetto ma fornire informazioni sufficienti in modo che gli sviluppatori possano approfondire man mano che acquisiscono familiarità con il tuo progetto.

2. Riferimento tecnico

In un'API REST/JSON, ogni endpoint è una funzione specifica con uno scopo. È importante disporre di documentazione tecnica che specifichi ciascun endpoint; definisce la descrizione, gli input e gli output che possono verificarsi; e fornisce esempi per vari clienti.

REST/JSON dispone di uno standard di specifica chiamato OpenAPI, che può guidarti attraverso i dettagli richiesti per documentare un'API. OpenAPI può anche generare documentazione di presentazione per la tua API.

3. Utilizzo

Gli utenti della tua API desiderano qualcosa di più delle semplici specifiche tecniche. Vogliono sapere come utilizzare la tua API in situazioni o casi specifici. La maggior parte dei potenziali utenti ha un problema e si rivolge alla tua API per risolverlo.

Un ottimo modo per presentare agli utenti la tua API è con una pagina "introduttiva". Questo può guidare l'utente attraverso un semplice caso d'uso che lo fa conoscere rapidamente i vantaggi della tua API.

Riepilogo

La documentazione è un componente chiave di qualsiasi API di successo. Quando crei la documentazione, pensa alle tre aree di interesse (onboarding, tecnica e utilizzo) che coprono queste basi e avrai un'API ben documentata.

Validazione

Uno degli aspetti più spesso trascurati dello sviluppo API è la convalida. La convalida è il processo di verifica dell'input da fonti esterne. Queste origini potrebbero essere un client che invia JSON o un servizio che risponde alla tua richiesta. Più che limitarsi a controllare i tipi, garantire che i dati siano quelli che dovrebbero essere può eliminare molti potenziali problemi. Comprendere i tuoi limiti e ciò su cui fai e su cui non hai il controllo è un aspetto importante della convalida.

La migliore strategia è convalidare ai margini prima che la logica abbia luogo. Quando un client invia alcuni dati alla tua API, applica la convalida prima di fare qualsiasi altra cosa con tali dati. Assicurati che un'e-mail sia un indirizzo e-mail effettivo, che la data sia formattata correttamente e che la stringa soddisfi i requisiti di lunghezza.

Questo semplice controllo aggiungerà sicurezza e coerenza alla tua applicazione. Inoltre, quando ricevi dati da un servizio, come un database o una cache, riconvalidalo per assicurarti che il risultato restituito soddisfi i controlli dei dati.

Puoi sempre convalidare manualmente o utilizzare librerie di funzioni di utilità come Lodash o Ramda. Funzionano benissimo per oggetti di dati di piccole dimensioni. Le librerie di convalida come Joi, Yup o Zod funzionano ancora meglio, poiché contengono convalide comuni che possono far risparmiare tempo e fatica e creare uno schema molto leggibile. Se hai bisogno di qualcosa di indipendente dalla lingua, guarda JSON Schema.

Riepilogo

La convalida non è attraente, ma può far risparmiare un sacco di tempo che altrimenti verrebbe impiegato nella risoluzione dei problemi e nella scrittura di script di migrazione dei dati. Non commettere l'errore di confidare che il tuo cliente invii dati puliti; non vuoi che dati errati vengano trapelati nella tua logica aziendale o nell'archivio dati persistente. Prenditi il tempo necessario per convalidare gli endpoint API e le risposte del servizio. Anche se all’inizio può causare qualche frustrazione, è molto più facile allentare i freni piuttosto che stringerli in seguito.

Test

Il test è una best practice per lo sviluppo del software e dovrebbe essere un requisito primario non funzionale. Definire una strategia di test può essere una sfida per qualsiasi progetto, comprese le API. Comprendi sempre i tuoi vincoli e definisci la tua strategia di conseguenza.

Il test di integrazione è uno dei metodi più efficaci per testare le API. In questo modello, il team di sviluppo crea un test per coprire una parte del flusso dell'applicazione, da un punto specifico a un altro. Un ottimo flusso di test di integrazione include il test del punto di ingresso dell'API e la simulazione del punto di richiesta al servizio. Scegliendo questi due punti, copri l'intera logica, dall'inizio della richiesta API alla richiesta di servizio, e il servizio fittizio ti fornisce una risposta da restituire alla risposta API.

Sebbene utilizzi mock, questo metodo consente di concentrarsi sul codice nel livello logico e di non dipendere dai servizi back-end o dalla logica di presentazione per eseguire il test. L'assenza di dipendenze rende l'esecuzione del test molto più affidabile, più facile da automatizzare e più semplice da includere nella pipeline di integrazione continua.

Una configurazione che utilizzo per i test di integrazione utilizza Tape, Test-server e Fetch-mock. Queste librerie mi consentono di eseguire test isolati sugli endpoint API dalla richiesta alla risposta, con Fetch-mock che cattura la richiesta in uscita al livello di persistenza.

Riepilogo

Sebbene tutti i tipi di test e controllo del tipo siano vantaggiosi per le API, i test di integrazione offrono il vantaggio maggiore in termini di efficacia rispetto al tempo di creazione e gestione. L'utilizzo di strumenti come Fetch-mock può fornire scenari di simulazione puliti al limite del servizio.

Concentrati sui fondamentali

Quando progetti e costruisci la tua applicazione e API, assicurati di includere questi quattro principi fondamentali. Questi non sono gli unici requisiti non funzionali da considerare; altri includono il monitoraggio delle applicazioni, la registrazione e la gestione delle API. Anche così, sicurezza, documentazione, convalida e test sono punti cruciali per progettare e costruire un'API di successo per qualsiasi caso d'uso.

Articoli correlati: