Solo POST? Mettiamo fine a questo assurdo dibattito sul design delle API

Di recente, una discussione su se progettare API utilizzando il "solo POST" ha attirato la mia attenzione. Dopo essermi immerso in questo dibattito, ho scoperto che non solo il problema di cui si discute è senza senso, ma rivela anche una cattiva comprensione dell'essenza del design delle API da parte di molti sviluppatori. Oggi, esploriamo a fondo le idee chiave del design delle API e vediamo perché questo dibattito non dovrebbe esistere in primo luogo.

L'idea sbagliata del "solo POST"#

Quegli sviluppatori che sostengono l'uso del "solo POST" per sostituire le specifiche delle API RESTful chiaramente non hanno colto il punto più importante del design delle API. I loro argomenti generalmente includono:

1. Semplificazione del design: Un solo metodo può gestire tutto
2. Sicurezza: I parametri POST non appaiono nell'URL
3. Flessibilità: POST può inviare qualsiasi struttura dati

A prima vista, questi argomenti sembrano avere un senso. Ma in realtà, questa visione confonde la scelta dei metodi HTTP con gli stili di design delle API, due livelli di problemi diversi. POST è solo un metodo del protocollo HTTP, mentre REST è uno stile di design delle API.

L'essenza del design delle API#

Prima di discutere stili di API specifici, dobbiamo capire qual è lo scopo principale del design delle API. Una buona API dovrebbe essere:

1. Chiara e comprensibile: Gli altri sviluppatori (incluso te stesso nel futuro) dovrebbero essere in grado di comprendere intuitivamente lo scopo di ciascun endpoint
2. Coerente: Seguire determinate specifiche per ridurre i costi di apprendimento
3. Estendibile: In grado di controllare facilmente le versioni e espandere le funzionalità
4. Efficiente: Considerare l'efficienza in termini di prestazioni e utilizzo delle risorse

API RESTful: Più di una semplice scelta di metodi HTTP#

L'API RESTful è solo uno dei molti stili di design delle API, concentrandosi sulle risorse e sulle operazioni su di esse. Prendiamo come esempio un semplice sistema di blog per vedere come viene progettata un'API RESTful:

1. Ottenere tutti gli articoli:

2. Ottenere un articolo specifico:

3. Creare un nuovo articolo:

4. Aggiornare un articolo:

5. Eliminare un articolo:

In questo esempio, possiamo vedere:

• L'API è progettata attorno alla risorsa "articolo"
• Vengono utilizzati diversi metodi HTTP per rappresentare diverse operazioni
• La struttura dell'URL è chiara, indicando la risorsa su cui si opera

Questo approccio di design rende l'API più intuitiva e autoesplicativa, facilitando agli sviluppatori la comprensione della funzione di ciascun endpoint.

RPC: Comprendere lo stile API dietro il "solo POST"#

L'obiettivo dello stile API RPC (Remote Procedure Call) è rendere le chiamate di servizi remoti semplici come chiamare funzioni locali.

Curiosamente, coloro che sostengono il "solo POST" potrebbero non rendersi conto che stanno effettivamente descrivendo lo stile RPC.

Rispetto alle API RESTful, RPC si concentra maggiormente sull'operazione stessa piuttosto che sulla risorsa. È per questo che le API in stile RPC utilizzano tipicamente una forma "verbo + sostantivo", come getProduct(productId) o createUser(userData).

In molte implementazioni RPC, tutte le operazioni vengono solitamente inviate tramite richieste POST allo stesso endpoint, con l'operazione specifica e i parametri specificati nel corpo della richiesta. È per questo che l'idea del "solo POST" è più vicina a RPC che a REST.

Ad esempio, una richiesta "ottenere prodotto" in stile RPC basata su HTTP potrebbe apparire così:

I moderni framework RPC, come gRPC, forniscono implementazioni più potenti ed efficienti. Utilizziamo questo esempio per dimostrare lo stile RPC:

Innanzitutto, definiamo il servizio e il formato del messaggio (usando Protocol Buffers):

Poi, usare questo servizio in un client Node.js è semplice come chiamare una funzione locale:

In questo esempio in stile RPC, possiamo vedere:

1. La definizione del servizio elenca chiaramente tutte le operazioni disponibili (in questo esempio semplificato, GetArticle e CreateArticle).
2. Ogni operazione ha tipi di richiesta e di risposta chiaramente definiti.
3. Il codice del client appare come una chiamata a una funzione asincrona locale, usando await per attendere il risultato, il che nasconde ulteriormente la complessità della comunicazione di rete.
4. Non è necessario costruire manualmente richieste HTTP o analizzare risposte JSON.

Anche se il livello sottostante può ancora utilizzare HTTP/2 come protocollo di trasporto, i framework RPC (come gRPC) offrono agli sviluppatori uno strato di astrazione che rende le chiamate remote simili a chiamate di funzione locali.

Pertanto, possiamo vedere che la maggior parte dei dibattiti su "solo POST" e API RESTful dovrebbe essenzialmente essere discussioni su questi due stili di API: REST e RPC. Tuttavia, la chiave è riconoscere che questi due stili hanno ciascuno i loro scenari applicabili, e la scelta dovrebbe essere basata sulle esigenze specifiche del progetto, non sulla preferenza personale.

REST contro RPC: Non c'è una superiorità o inferiorità assoluta#

Ora che comprendiamo le differenze tra REST e RPC, vediamo i loro rispettivi scenari applicabili:

1. REST è adatto a:
   • Applicazioni orientate alle risorse (come sistemi di gestione dei contenuti, piattaforme di blog, siti di e-commerce)
   • Scenari che richiedono un buon supporto per la cache (le richieste GET sono naturalmente memorizzabili nella cache)
   • Progetti che vogliono sfruttare la semantica HTTP (come l'uso di codici di stato appropriati)
   • API di tipo pubblico che richiedono una buona riconoscibilità e auto-descrizione
2. RPC è adatto a:
   • Applicazioni orientate alle azioni (come operazioni complesse di elaborazione dati, controllo di workflow)
   • Sistemi che richiedono alte prestazioni e bassa latenza (come sistemi di trading in tempo reale)
   • Comunicazione tra microservizi interni (che possono richiedere una maggiore flessibilità nel passaggio dei parametri)
   • Quando le operazioni non possono essere semplicemente mappate alle operazioni CRUD (Create, Read, Update, Delete)

La scelta dello stile dovrebbe essere basata sulle esigenze specifiche. In alcuni casi, potresti persino utilizzare entrambi gli stili all'interno dello stesso sistema per soddisfare le esigenze di diverse parti.

Conclusione#

1. Il cuore del design delle API sta nella chiarezza, coerenza, estendibilità ed efficienza, non nel rispettare un metodo o uno stile particolare.
2. Sia RESTful che RPC sono paradigmi di design delle API maturi. La scelta tra loro dovrebbe essere basata sulle esigenze del progetto, non sulle preferenze personali.
3. Se decidi di utilizzare il "solo POST", allora progetta la tua API secondo lo stile RPC. Come RESTful, è una specifica API comunemente usata nell'industria, ma dovrebbe essere utilizzata negli scenari appropriati.
4. Non lasciarti confondere dai dettagli tecnici superficiali. Ciò che conta davvero è se la tua API riesce a servire efficacemente i tuoi utenti e le esigenze del business.
5. Quando progetti API, dedica più tempo a pensare al tuo modello di risorse, alla logica di business e alle esigenze degli utenti, piuttosto che ossessionarti su quale metodo HTTP utilizzare.

Spostiamo la nostra attenzione lontano da questi argomenti inutili e concentriamoci sulla progettazione di API realmente eccellenti. Dopo tutto, la tecnologia serve per risolvere problemi, non per crearli.