Progettazione orientata alle risorse

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

L'obiettivo di questa guida alla progettazione è aiutare gli sviluppatori a progettare API di rete semplici, coerenti e di facile utilizzo. Allo stesso tempo, aiuta anche a convergere i progetti di API RPC basate su socket con API REST basate su HTTP.

Le API RPC sono spesso progettate in termini di interfacce e metodi. Visto il numero sempre maggiore di questi elementi, il risultato finale può sembrare un'operazione complessa e confondente, poiché gli sviluppatori devono imparare a utilizzare ogni singolo metodo. Ovviamente questa operazione richiede molto tempo ed è soggetta a errori.

È stato introdotto lo stile architetturale di REST, progettato principalmente per funzionare bene con HTTP/1.1, ma anche per affrontare questo problema. Il suo principio fondamentale è definire le risorse con nome che possono essere manipolate utilizzando un numero limitato di metodi. Le risorse e i metodi sono noti come nomi e verbi delle API. Con il protocollo HTTP, i nomi delle risorse vengono mappati naturalmente agli URL e i metodi vengono mappati in modo naturale ai metodi HTTP POST, GET, PUT, PATCH e DELETE. Ne consegue una minore quantità di informazioni da apprendere, poiché gli sviluppatori possono concentrarsi sulle risorse e sulla loro relazione e presumere che abbiano lo stesso ridotto numero di metodi standard.

Su Internet, le API REST HTTP sono state un grande successo. Nel 2010, circa il 74% delle API di rete pubblica erano API REST HTTP (o simili a REST), la maggior parte delle quali utilizzava JSON come formato dei cavi.

Sebbene le API HTTP/JSON siano molto apprezzate su Internet, la quantità di traffico trasportata è inferiore a quella delle API RPC tradizionali. Ad esempio, circa la metà del traffico Internet in America durante il periodo di picco si riferisce ai contenuti video e poche persone valuterebbero la possibilità di utilizzare le API HTTP/JSON per fornire tali contenuti per ovvi motivi legati alle prestazioni. All'interno dei data center, molte aziende utilizzano API RPC basate su socket per trasportare la maggior parte del traffico di rete, che può comportare ordini di grandi quantità di dati (misurati in byte) rispetto alle API HTTP/JSON pubbliche.

In realtà, sono necessarie sia le API RPC che le API HTTP/JSON per diversi motivi e, idealmente, una piattaforma API dovrebbe fornire il miglior supporto per tutti i tipi di API. Questa guida alla progettazione ti aiuta a progettare e sviluppare API conformi a questo principio. Per farlo, applica principi di progettazione orientati alle risorse alla progettazione generale dell'API e definisce molti pattern di progettazione comuni per migliorare l'usabilità e ridurre la complessità.

Che cos'è un'API REST?

Un'API REST è modellata come raccolte di risorse indirizzabili singolarmente (i nomi dell'API). Alle risorse viene fatto riferimento con i nomi delle risorse e manipolate tramite un piccolo insieme di metodi (detti anche verbi o operazioni).

I metodi standard per le API Google REST (detti anche 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 designer di API per funzionalità che non corrispondono facilmente a uno dei metodi standard, come le transazioni di database.

Flusso di progettazione

La guida alla progettazione suggerisce di seguire i passaggi riportati di seguito durante la progettazione delle API orientate alle risorse (ulteriori dettagli nelle sezioni specifiche riportate 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.
  • Decidi gli schemi delle risorse.
  • Allega un set minimo di metodi alle risorse.

Risorse

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

  • Una raccolta contiene un elenco delle 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 di raccolta.

Ad esempio, l'API Gmail contiene una raccolta di utenti, ognuno con una raccolta di messaggi, una raccolta di thread, una raccolta di etichette, una risorsa profilo e diverse risorse di impostazione.

Sebbene vi sia un certo allineamento concettuale tra sistemi di archiviazione e API REST, un servizio con un'API orientata alle risorse non è necessariamente un database e ha un'enorme flessibilità nel modo di interpretare 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à). Un'API tipica orientata alle risorse espone un numero elevato di risorse, con numerosi metodi. I metodi possono essere metodi standard o personalizzati. Per questa guida, i metodi standard sono: List, Get, Create, Update e Delete.

Dove la funzionalità API si riferisce naturalmente a uno dei metodi standard, il metodo deve essere utilizzato nella progettazione dell'API. Per funzionalità che non corrispondono naturalmente a uno dei metodi standard, è possibile usare 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 le transazioni di database o l'analisi dei dati.

Esempi

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

In questi esempi, l'asterisco indica una risorsa specifica non presente nell'elenco.

API Gmail

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

  • Servizio API: gmail.googleapis.com
    • Una raccolta di utenti: users/*. Ciascun 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 di cronologia delle modifiche: users/*/history/*.
      • Una risorsa che rappresenta il profilo utente: users/*/profile.
      • Una risorsa che rappresenta le impostazioni dell'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 dispone delle seguenti risorse.
      • Una raccolta di operazioni: projects/*/instances/*/databases/*/operations/*.
      • Una raccolta di sessioni: projects/*/instances/*/databases/*/sessions/*.