5 passaggi per creare un'API di successo

È la natura dello sviluppo del software. Gli sviluppatori creano software pensando all'utente finale. Sembra piuttosto semplice, ma a volte quegli utenti sono anche colleghi sviluppatori. Non hanno bisogno di cose scomposte per loro. Non hanno nemmeno bisogno della semplicità. Tutto ciò che vogliono è l'accesso, un modo per integrare il tuo software con il loro. È qui che entra in gioco un'API (interfaccia di programmazione dell'applicazione). Spero di evidenziare cinque passaggi che è possibile eseguire per creare un'API di successo.

Fai i tuoi compiti

Quando si tratta di sviluppo software, nessuno di noi vuole reinventare la ruota. A questo punto, quasi tutte le grandi società Web dispongono di API per i loro prodotti software. Studia queste API e prova a raccogliere le diverse decisioni di progettazione che sono state prese nel crearle.

Esistono molte tecnologie diverse, ma la maggior parte delle API che vedrai utilizzerà un'interfaccia RESTful o SOAP. Se sei sulla recinzione per quale interfaccia API utilizzerai, ti suggerirei di seguire un approccio RESTful usando il protocollo HTTP. È più semplice di SOAP, attualmente è più popolare e sarà più facile iniziare quando si utilizza un prodotto software basato sul Web.

Sii coerente

Una delle cose che gli sviluppatori apprezzano di più è la coerenza. Ciò include, tra l'altro, indirizzabilità, argomenti di input, formati di output e gestione degli errori.

Quando si utilizza un approccio RESTful, esistono diversi schemi di denominazione URI. Ognuno ha i suoi sostenitori, quindi scegline uno e seguilo. Lo stesso vale per la struttura di input e output. La maggior parte delle API supporta l'utilizzo di XML e JSON come formati di input e output. Suggerirei di supportare entrambi, ma scegliendo un formato predefinito.

Per l'input, i requisiti di input devono essere denominati in modo coerente e dovrebbero avere senso nel contesto della chiamata API che si sta effettuando. Per l'output, assicurarsi di utilizzare layout di struttura dati comuni. Se si esegue il wrapping dell'output di una chiamata API in a Tag XML, considera di farlo con le altre tue chiamate.

È pratica comune includere una sorta di flag di stato nei dati di output che si inviano al client. Quando si utilizza un approccio API RESTful, questo dovrebbe essere fatto utilizzando i codici di stato HTTP. Ad esempio, se hai appena elaborato una richiesta PUT su un oggetto dati esistente, il codice di stato HTTP che includi nella tua risposta varierà a seconda dell'esito della richiesta.

Invece di un flag arbitrario che indica lo stato della chiamata, è possibile utilizzare un codice di stato "200 OK" standard per indicare che la richiesta ha avuto esito positivo, mentre un codice di stato "400 Richiesta non valida" potrebbe indicare che la richiesta era valido. Esistono diversi codici di stato HTTP che possono essere utilizzati in diverse situazioni.

Usa OAuth

La maggior parte dei prodotti software prevede una sorta di autenticazione dell'utente per accedere alle risorse protette per quell'utente. Quando si tratta di API, fare in modo che il client raccolga le credenziali dell'utente da inviare al server è una cattiva pratica. È qui che entra in gioco OAuth.

OAuth offre molti vantaggi rispetto all'autenticazione di nome utente / password di terze parti. Soprattutto, il client non ha mai accesso alle credenziali dell'utente. L'utente viene reindirizzato al server quando accede. Dopo che l'utente accede al sito, viene reindirizzato al client in cui il client riceverà un token di accesso da utilizzare nelle richieste future a risorse protette.

Un altro importante vantaggio dell'utilizzo di OAuth è la capacità dell'utente di annullare l'accesso al client in qualsiasi momento. Se l'utente decide che, per qualsiasi motivo, non desidera più che il client sia in grado di accedere alle risorse protette per suo conto, passa semplicemente a un'interfaccia creata dall'utente e annulla l'accesso al client.

Inizia presto

Una delle cose più importanti che puoi fare per rendere la tua API un successo è iniziare presto. Quando scrivi quella funzione per creare una voce nel tuo database, vai avanti e prenditi il ​​tempo extra e scrivi un'interfaccia API per essa.

Scrivi una buona documentazione

Niente uccide un'API più velocemente di non avere una buona documentazione. Mentre alcuni sviluppatori possono prendere un'API scarsamente documentata e capire come dovrebbe funzionare, la maggior parte non lo vorrà.

È necessario documentare ogni chiamata API disponibile e classificare le chiamate API in base al tipo di dati su cui agiscono. Oltre a documentare gli endpoint per le chiamate API stesse, è necessario definire sistematicamente gli argomenti di input obbligatori e facoltativi nonché le strutture dei dati di output. Gli argomenti di input devono elencare un valore predefinito, se presente, e indicare anche il formato dati previsto, ad esempio un numero o una stringa. Infine, ogni chiamata API dovrebbe avere un elenco di condizioni di errore e codici di stato.

Per completare la documentazione, assicurarsi di includere uno o due esempi per scenari di input e output comuni per ogni chiamata API.

Sviluppo API: Keep It Simple

Sebbene possa sembrare che lo sviluppo di un'API sia uno sforzo complicato, l'idea di un'API stessa non è un nuovo concetto e c'è una grande quantità di documentazione disponibile su ogni argomento che abbiamo toccato qui. Assicurati solo di utilizzare le buone pratiche in cui puoi trovarle e di fornire un'interfaccia coerente e ben documentata.