L'obiettivo di questa guida alla progettazione è aiutare gli sviluppatori a progettare semplici coerenti e facili da usare. Allo stesso tempo, aiuta anche a convergere i progetti delle API RPC basate su socket con le API REST basate su HTTP.
Le API RPC sono spesso progettate in termini di interfacce e metodi. Man mano che se ne aggiungono di più nel tempo, il risultato finale può essere un'interfaccia API scoraggiante e confusa, poiché gli sviluppatori devono imparare ogni metodo singolarmente. Ovviamente, questa procedura è un'operazione lunga e soggetta a errori.
È stato introdotto lo stile di architettura
REST, progettato principalmente per funzionare bene con HTTP/1.1, ma anche per contribuire a risolvere questo problema. Il suo principio di base è definire risorse denominate che possono essere manipolate utilizzando un numero limitato di metodi. Le risorse e i metodi vengono chiamati
rispettivamente sostantivi e verbi delle API. Con il protocollo HTTP, i nomi delle risorse
corrispondono naturalmente agli URL e i metodi corrispondono naturalmente ai metodi HTTP POST,
GET, PUT, PATCH e DELETE. Ciò si traduce in molte meno cose da imparare,
poiché gli sviluppatori possono concentrarsi sulle risorse e
sulla loro relazione e dare per scontato
che hanno lo stesso numero ridotto di metodi standard.
Su internet, le API REST HTTP hanno avuto un enorme successo. Nel 2010, circa il 74% delle API delle reti pubbliche erano API HTTP REST (o REST), la maggior parte che utilizzava JSON come il formato dei cavi.
Sebbene le API HTTP/JSON siano molto diffuse su internet, la quantità di traffico che trasportano è inferiore a quella delle API RPC tradizionali. Ad esempio, circa la metà del traffico internet in America nelle ore di punta è costituito da contenuti video e poche persone prenderebbero in considerazione l'utilizzo di API HTTP/JSON per pubblicare questi contenuti per ovvie ragioni di prestazioni. All'interno dei data center, molte aziende utilizzano API RPC basate su socket per trasportare la maggior parte del traffico di rete, il che può comportare ordini di grandezza in più (misurati in byte) rispetto alle API HTTP/JSON pubbliche.
In realtà, sia le API RPC sia le API HTTP/JSON sono necessarie per vari motivi e, idealmente, una piattaforma API dovrebbe fornire il supporto migliore per tutti i tipi di API. Questa guida alla progettazione ti aiuta a progettare e creare API conformi a questo principio. Ciò avviene applicando i principi di progettazione orientati alle risorse alla progettazione generale delle API e definendo molti pattern di progettazione comuni per migliorare l'usabilità e ridurre la complessità.
Che cos'è un'API REST?
Un'API REST è modellata come raccolta di risorse con indirizzi singoli (i nomi dell'API). Le risorse vengono richiamate con i relativi nomi e manipolate tramite un piccolo insieme di metodi (noti anche come verbi o operazioni).
I metodi standard per le API Google REST (noti anche come metodi REST) sono List, Get, Create, Update e Delete. Metodi personalizzati
(noti anche come verbi personalizzati o operazioni personalizzate) sono disponibili anche
ai progettisti di API per funzionalità che difficilmente vengono mappate a uno dei
metodi standard come le transazioni nei database.
Flusso di progettazione
La guida alla progettazione suggerisce di prendere i seguenti passaggi nella progettazione API orientate (maggiori dettagli sono trattati nelle sezioni specifiche di seguito):
- Determinare i tipi di risorse forniti da un'API.
- Determinare le relazioni tra le risorse.
- Decidi gli schemi dei nomi delle risorse in base a tipi e relazioni.
- Scegli gli schemi delle risorse.
- Collega un insieme minimo di metodi alle risorse.
Risorse
Un'API orientata alle risorse è generalmente modellata come una gerarchia di risorse, in cui ogni nodo è una risorsa semplice o una risorsa raccolta. Per praticità, vengono spesso chiamate rispettivamente risorsa e raccolta.
- Una raccolta contiene un elenco di risorse dello stesso tipo. Ad esempio, un utente ha una raccolta di contatti.
- Una risorsa ha uno stato e zero o più risorse secondarie. Ogni risorsa secondaria può essere una risorsa semplice o una risorsa raccolta.
Ad esempio, l'API Gmail ha una raccolta di utenti, ogni utente ha una raccolta di messaggi, una raccolta di thread, una raccolta di etichette, una risorsa del profilo e diverse risorse di impostazioni.
Sebbene esista un certo allineamento concettuale tra i sistemi di archiviazione e le API REST, un servizio con un'API orientata alle risorse non è necessariamente un database e offre un'enorme flessibilità nel modo in cui interpreta le risorse e i metodi. Ad esempio, la creazione di un evento di calendario (risorsa) può creare eventi aggiuntivi per i partecipanti, inviare inviti via email ai partecipanti, prenotare sale conferenze e aggiornare le pianificazioni delle videoconferenze.
Metodi
La caratteristica principale di un'API orientata alle risorse è che enfatizza
risorse (modello dei dati) rispetto ai metodi eseguiti sulle risorse
(funzionalità). Una tipica API orientata alle risorse espone un numero elevato
di risorse con un numero ridotto di metodi. I metodi possono essere metodi standard o personalizzati. Per questa guida, i metodi standard sono: List, Get, Create, Update e Delete.
Mentre la funzionalità API è mappata naturalmente a uno dei metodi standard, questo metodo deve essere usato nella progettazione dell'API. Per le funzionalità che non corrispondono naturalmente a uno dei metodi standard, metodi personalizzati possono essere utilizzati. I metodi personalizzati offrono lo stesso libertà di progettazione rispetto alle API RPC tradizionali, che possono essere utilizzate per implementare schemi di programmazione comuni, come l'analisi dei dati o le transazioni nei database.
Esempi
Le seguenti sezioni presentano alcuni esempi reali su come applicare la progettazione di API orientata alle risorse per servizi su larga scala. Puoi trovare altri esempi nel repository delle API di Google.
In questi esempi, l'asterisco indica una risorsa specifica nell'elenco.
API Gmail
Il servizio API Gmail implementa l'API Gmail ed espone la maggior parte dei dati di Gmail funzionalità. Ha il seguente modello di risorsa:
- Servizio API:
gmail.googleapis.com- Una raccolta di utenti:
users/*. Ogni utente ha le seguenti risorse.- Una raccolta di messaggi:
users/*/messages/*. - Una raccolta di thread:
users/*/threads/*. - Una raccolta di etichette:
users/*/labels/*. - Una raccolta di cronologia delle modifiche:
users/*/history/*. - Una risorsa che rappresenta il profilo utente:
users/*/profile. - Una risorsa che rappresenta le impostazioni utente:
users/*/settings.
- Una raccolta di messaggi:
- Una raccolta di utenti:
API Cloud Pub/Sub
Il servizio pubsub.googleapis.com implementa il parametro
API Cloud Pub/Sub, che definisce il seguente modello di risorse:
- Servizio API:
pubsub.googleapis.com- Una raccolta di argomenti:
projects/*/topics/*. - Una raccolta di abbonamenti:
projects/*/subscriptions/*.
- Una raccolta di argomenti:
API Cloud Spanner
Il servizio spanner.googleapis.com implementa l'API Cloud Spanner, che definisce il seguente modello di risorse:
- Servizio API:
spanner.googleapis.com- Una raccolta di istanze:
projects/*/instances/*. Ogni istanza ha le seguenti risorse. - Una raccolta di operazioni:
projects/*/instances/*/operations/*. - Una raccolta di database:
projects/*/instances/*/databases/*. Ogni database ha le seguenti risorse.- Un insieme di operazioni:
projects/*/instances/*/databases/*/operations/*. - Una raccolta di sessioni:
projects/*/instances/*/databases/*/sessions/*.
- Un insieme di operazioni:
- Una raccolta di istanze: