Design orientato alle risorse

L'obiettivo di questa Guida alla progettazione è aiutare gli sviluppatori a progettare API in rete semplici, coerenti e facili da usare. Allo stesso tempo, favorisce anche la convergenza delle progettazioni di API RPC basate su socket con API REST basate su HTTP.

Le API RPC sono spesso progettate in termini di interfacce e metodi. Man mano che vengono aggiunti sempre più di questi metodi nel tempo, il risultato finale può essere una superficie API complessa e confuso, dovuta al fatto che gli sviluppatori devono imparare ogni metodo singolarmente. Ovviamente si tratta di un'operazione dispendiosa in termini di tempo e soggetta a errori.

È stato introdotto lo stile architetturale di REST, progettato principalmente per funzionare bene con HTTP/1.1, ma anche per contribuire a risolvere questo problema. Il suo principio fondamentale consiste nel definire risorse denominate che possono essere manipolate utilizzando un numero ridotto di metodi. Le risorse e i metodi sono noti come sostantivi e verbi delle API. Nel protocollo HTTP, i nomi delle risorse vengono mappati naturalmente agli URL, mentre i metodi ai metodi HTTP POST, GET, PUT, PATCH e DELETE. Questo si traduce in molte meno cose da imparare, dato che gli sviluppatori possono concentrarsi sulle risorse e sulle loro relazioni e presumere di avere 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 di rete pubbliche erano API REST HTTP (o simili a REST), la maggior parte utilizzando JSON come formato di rete.

Sebbene le API HTTP/JSON siano molto popolari su Internet, la quantità di traffico che trasportano è inferiore rispetto alle API RPC tradizionali. Ad esempio, circa la metà del traffico Internet americano nei periodi di punta è costituito da contenuti video e poche persone potrebbero considerare l'utilizzo di API HTTP/JSON per pubblicare questi contenuti per ovvi motivi 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ù di dati (misurati in byte) rispetto alle API HTTP/JSON pubbliche.

In realtà, sia le API RPC che le API HTTP/JSON sono necessarie per vari motivi e, idealmente, una piattaforma API dovrebbe fornire il miglior supporto possibile per tutti i tipi di API. Questa guida alla progettazione ti aiuta a progettare e creare API conformi a questo principio. Lo fa applicando principi di progettazione orientati alle risorse alla progettazione generale delle API e definisce molti modelli di progettazione comuni per migliorare l'usabilità e ridurre la complessità.

Che cos'è un'API REST?

Un'API REST è modellata come raccolte di risorse con indirizzi singoli (i nomi dell'API). Le risorse vengono utilizzate per fare riferimento ai relativi nomi delle risorse e manipolate tramite un piccolo insieme di metodi (chiamati anche verbi o operazioni).

I metodi standard per le API REST di Google (noti anche come metodi REST) sono List, Get, Create, Update e Delete. I metodi personalizzati (noti anche come verbi personalizzati o operazioni personalizzate) sono disponibili anche per i progettisti di API per funzionalità che difficilmente si associano a uno dei metodi standard, come le transazioni del database.

Flusso di progettazione

La guida alla progettazione suggerisce di intraprendere i seguenti passaggi durante la progettazione di API orientate alle risorse (ulteriori dettagli nelle sezioni specifiche di seguito):

Determinare i tipi di risorse forniti da un'API.
Determina le relazioni tra le risorse.
Decidi gli schemi dei nomi delle risorse in base ai tipi e alle relazioni.
Decidi gli schemi delle risorse.
Collega un insieme minimo di metodi alle risorse.

Risorse

Un'API orientata alle risorse è generalmente modellata come gerarchia di risorse, in cui ogni nodo è una risorsa semplice o una risorsa di raccolta. Per praticità, vengono spesso definiti rispettivamente una risorsa e una raccolta.

Una raccolta contiene un elenco di risorse dello stesso tipo. Ad esempio, supponiamo che un utente abbia una raccolta di contatti.
Una risorsa ha uno stato e nessuna risorsa secondaria o più. Ogni sottorisorsa può essere una risorsa semplice o di raccolta.

Ad esempio, l'API Gmail comprende una raccolta di utenti, ciascuno dei quali dispone di una raccolta di messaggi, di thread, di etichette, di una risorsa del profilo e di varie risorse di impostazione.

Sebbene esista un allineamento concettuale tra i sistemi di archiviazione e le API REST, un servizio con un'API orientata alle risorse non è necessariamente un database e ha 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 i programmi delle videoconferenze.

Metodi

La caratteristica principale di un'API orientata alle risorse è che enfatizza le 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. Possono essere sia i metodi standard che quelli personalizzati. Per questa guida, i metodi standard sono: List, Get, Create, Update e Delete.

Se la funzionalità dell'API è mappata naturalmente a uno dei metodi standard, tale metodo deve essere utilizzato nella progettazione dell'API. Per funzionalità che non sono mappate naturalmente a uno dei metodi standard, possono essere utilizzati dei metodi personalizzati. I metodi personalizzati offrono la stessa libertà di progettazione delle API RPC tradizionali, che possono essere utilizzate per implementare pattern di programmazione comuni, come transazioni sul database o analisi dei dati.

Esempi

Le seguenti sezioni presentano alcuni esempi reali su come applicare la progettazione di API orientate alle risorse a servizi su larga scala. Puoi trovare altri esempi nel repository delle API di Google.

In questi esempi, l'asterisco indica una risorsa specifica dell'elenco.

API Gmail

Il servizio API Gmail implementa l'API Gmail ed espone la maggior parte delle funzionalità di Gmail. Ha il seguente modello di risorse:

Servizio API: gmail.googleapis.com
- Una raccolta di utenti: users/*. Ogni utente dispone delle seguenti risorse.
  - Una raccolta di messaggi: users/*/messages/*.
  - Una raccolta di thread: users/*/threads/*.
  - Una raccolta di etichette: users/*/labels/*.
  - Una raccolta della cronologia delle modifiche: users/*/history/*.
  - Una risorsa che rappresenta il profilo utente: users/*/profile.
  - Una risorsa che rappresenta le impostazioni utente: users/*/settings.

API Cloud Pub/Sub

Il servizio pubsub.googleapis.com implementa l'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/*.

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 contiene le seguenti risorse.
  - Una raccolta di operazioni: projects/*/instances/*/databases/*/operations/*.
  - Una raccolta di sessioni: projects/*/instances/*/databases/*/sessions/*.