Per chi si approccia o per chi lavora nel mondo delle API, ci sono alcuni formati principali da conoscere.

Nell'articolo di oggi esamineremo tre delle più importanti: REST, SOAP e GraphQL, andando ad identificarne differenze, gli aspetti positivi e quelli negativi.

REST

Le API REST, ovvero Representational State Transfer, forniscono a un client l'accesso a una rappresentazione dello stato di una risorsa desiderata. Quando chiamato, il server trasferirà la rappresentazione al client.

Ad esempio, chiamare l'API di Twitter per recuperare un elenco di tweet (la risorsa) ci fornisce lo stato di quei tweet: utenti, ora, posizione, ecc. Spesso la rappresentazione restituita al client è un payload in formato JSON, ma può anche assumere diversi formati come XML o HTML.

Per effettuare unarichiesta, il server ha bisogno dal client di:

·        un endpoint

·        un'operazione

Gli endpoint fungono daidentificatore per la risorsa desiderata: l'URL (Uniform Resource Locator!) didove trovarla. Le operazioni assumono la forma di un metodo HTTP come GET, PUT,POST o DELETE.

La maggior parte diquelle che chiamiamo "API RESTFUL" sono in realtà solo"interfacce HTTP" in quanto non soddisfano pienamente gli standardper l'architettura REST. Quando si parla di REST, NEL linguaggio colloquiale siintende generalmente un'API Web con un'interfaccia HTTP.

SOAP

SOAP, Simple ObjectAccess Protocol, si concentra su tre caratteristiche chiave: estensibilità,neutralità (non specifica del protocollo) e indipendenza (non specificadell'architettura). SOAP richiede la trasmissione di dati in XML, ma siccome èindipendente dal protocollo, può utilizzare HTTP, SMTP o qualsiasi altra formaper negoziare e inviare richieste di messaggi. Una richiesta SOAP deve semprecontenere una envelope ( visualizzabile come una sorta di busta ) cheidentifica l'XML come messaggio SOAP e un body che contenga le informazioni dichiamata e risposta. Può contenere facoltativamente intestazioni ed errori(usati per descrivere gli errori).

Ecco come appare unarichiesta SOAP di base - Postman è un client REST ma può effettivamente inviarerichieste in SOAP utilizzando la codifica XML:

SOAP vs REST

Sulla carta la differenzachiave tra REST e SOAP è rappresentato dai dati a cui si vuole accedere. REST èl'ideale per il recupero dei dati. Viene spesso utilizzato quando esponiamo APIpubbliche o di partners su Internet. È l'ideale per questo scopo in quantofornisce un accesso isolato e controllato a risorse nominali.

Al contrario, SOAP faemergere la logica dell'applicazione effettiva attraverso un diverso set diinterfacce e pertanto è l'ideale per eseguire operazioni.

In realtà nella maggiorparte dei casi d'uso si potrebbe ottenere gli stessi risultati sfruttando SOAPo REST. Ognuno di essi ha configurazioni leggermente diverse, ma la discresiatra le metodologie rimane minimale.

SOAP è tecnicamente ilprotocollo API "legacy" più vecchio (creato da Microsoft stessa) - maREST non è più l’opzione più moderna. 

GRAPHQL

La maggior parte delleapplicazioni moderne, come la maggior parte di cui sviluppa applicazioni, utilizzaAPI REST da molto tempo. Negli ultimi anni tuttavia, è sempre maggiorel’entusiasmo verso questo nuovo “REST 2.0”, questo nuovo linguaggio diinterrogazione alternativo denominato GraphQL. In che modo GraphQL sidifferenzia dal resto?

GraphQL è stato creato daFacebook nel 2012 per supportare la propria infrastruttura di applicazionimobili e quindi reso open source nel 2015. È una specifica per il recupero deidati che funziona anche come linguaggio di query API (GraphQL).

Sebbene REST sia un'”architettura”e GraphQL sia una “specifica”, entrambi gli strumenti vengono utilizzati percreare e interagire con le API. GraphQL non è vincolato da alcun protocollospecifico, ma può anche utilizzare HTTP, come fatto da REST.

Di seguito un esempio di unachiamata GraphQL inviata tramite Postman:

GraphQL vs. REST

Si potrebbero scriverelibri come risultato dell’analisi di dettaglio delle differenza tra GraphQL eREST. Ci focalizziamo di seguito pertanto su alcuni punti principali.

Recupero dati

Il recupero dei dati èspesso considerato il più grande miglioramento di GraphQL rispetto a REST. Inuna normale API REST, il recupero dei dati da un server potrebbe richiedere di farerichieste a più di un endpoint. GraphQL riduce i punti di accesso ai dati sulserver a un singolo endpoint. Per questo motivo una richiesta è sufficiente perottenere sia la nostra risorsa che le risorse correlate.

Recupero dati eccessivo/insufficiente

Le richieste REST spessoportano a un recupero eccessivo o insufficiente delle informazioni perché gliendpoint restituiscono strutture di dati fisse. La maggior parte delle volte,riceviamo un grande payload quando abbiamo il bisogno di interrogare un singolocampo, andando quindi a sprecare tutte le informazioni extra.

Potremmo addiritturaanche non vedere le informazioni che desideriamo alla nostra prima richiestaREST e costringendoci quindi ad effettuare più chiamate a causa di questo.

GraphQL, come linguaggiodi query, non soffre di questo problema. Possiamo progettare query perincludere esattamente le informazioni da noi richieste.

La seguente query GraphQLottiene solo il corpo di un tweet (No, Twitter non ha un'API GraphQL):

{
      tweet{
        body
      }
    }
    {
      "data": {
        "tweet": {
          "body": "Postman"
        }
      }
    }

Gestione degli errori

REST si appoggia su HTTPper la gestione dei suoi errori. GraphQL, anziché appoggiarsi ad HTTP - con i codicidi stato HTTP restituiti come 404, 503, 500 ecc. - ottiene sempre uno stato dirisposta 200 OK, indipendentemente dal risultato effettivo. In caso di erroredurante l'esecuzione di una query GraphQL, il messaggio di errore viene inviatoal client insieme alla risposta, in questo modo:

Caching

REST utilizza HTTP, cheha incorporato la memorizzazione nella cache. Di conseguenza, il client puòutilizzare la cache per evitare di recuperare lo stesso dato due volte.GraphQL, d'altra parte, non ha un proprio caching. Ciò significa che i clientdevono memorizzare nella cache da parte loro.

Versioning

Quando lavoriamo con leAPI REST, vediamo frequenti versioni: a volte il campo che stai cercando direcuperare esiste solo in una API v2 ed è stato deprecato nella v3. Ilcontrollo delle versioni rende il codice da entrambi i lati di un'API menogestibile.

Le API GraphQL possonoessere modificate con nuovi campi o tipi senza alcun impatto sulle queryesistenti. I campi possono anche essere contrassegnati come deprecati perescluderli dalle risposte del server.

SOAP vs GraphQL

Si può dire che GraphQLcombini i punti di forza di SOAP e REST.

GraphQL e SOAP utilizzanoentrambi un solo endpoint per accedere ai dati. Tuttavia, GraphQL è più leggero(avendo payload più piccoli) e provoca un minor stress sulle reti. Entrambi iformati sono fortemente tipizzati: dobbiamo dichiarare i tipi di dati (Integer,String, Date, ecc.) quando li utilizziamo e questo provoca meno “attrito” tra iservizi.

Una cosa che manca aentrambi i formati è la memorizzazione nella cache, che richiede l'uso di altristrumenti per tal fine.

Quale scelgo?

Nessun formato API è lasoluzione perfetta, hanno tutte i loro punti di forza e di debolezza.

·        REST e JSONcontinuano ad essere utilizzate per la maggior parte delle nuove API, perlomenoper la fase iniziale, in quanto sono meno pesanti in termini di larghezza dibanda e più facilmente comprensibili agli sviluppatori che le creano o leutilizzano. Di conseguenza, REST rimane la tecnologia di riferimento per lamaggior parte delle API pubbliche.

·        SOAP è ancorautilizzato in determinate situazioni, ma è ampiamente messo in ombra, avendoormai anni sulle spalle

·        GraphQL harisolto molti problemi di REST e vanta innumerevoli interessanti funzionalità

Decidere pertanto suquale protocollo puntare, quale utilizzare, come sempre, dipende dallanecessità.