lunedì 26 ottobre 2020

Documentare le API: ci sono diversi tipi di API...

Nei primi 3 articoli di questa serie, ho provato a definire "la cornice" di una tematica complessa:

  1. Api "economy": quale impatto sulla Comunicazione Tecnica?
  2. Documentare le API? Le risposte nascono dalle domande...
  3. Documentare le API: per quale audience?

Ora provo ad analizzare "il quadro", che è composto da diverse aree in relazione tra di loro, come in un quadro di Mondrian:


Prima di tutto, cominciamo a distinguere tra i diversi tipi di API che potremmo ritrovarci a dover documentare.

Riprendiamo lo spunto dal report di SmartBear.

Il grafico indica i tipi di API oggetto di attenzione tra i partecipanti al sondaggio:


CLASSIFICAZIONE DELLE API

Di seguito, vi fornisco una breve panoramica delle tipologie di API più diffuse.
Se volete approfondire ogni singola area, potete trovare del materiale in rete a partire dai link che vi segnalo.

In un prossimo blocco di articoli andrò ad approfondire le questioni di documentazione inerenti alle REST API, che sono oggi prevalenti sul mercato. Ma vedremo che i concetti generali e le best practice sono applicabili anche fuori dal perimetro delle REST API, con eventuali adattamenti.

REST API

Nell'architettura REST (REpresentational State Transfer), il server non memorizza lo stato della sessione del client. Ogni richiesta HTTP dal client al server deve contenere tutte le informazioni necessarie (payload) e lo stato della sessione è mantenuto lato client. Il server non si basa sulle informazioni provenienti da richieste precedenti. Il client è responsabile dell'archiviazione e della gestione di tutte le informazioni relative allo stato dell'applicazione.

Le REST API utilizzano diversi formati di dati tra cui TXT,  XML e JSON. L'utilizzo di formati di dati più semplici rende i payload più leggeri, il che rende le API REST più adatte a una gamma più ampia di applicazioni.

Ad esempio, REST API con payload JSON sono molto utilizzate in integrazioni IoT, dove diversi tipi di dispositivi, non sempre dotati di grandi capacità di memoria e di calcolo, devono scambiarsi informazioni.

Attraverso una REST API ci si relaziona con una "risorsa", identificata da una URL. I "consumatori" inviano richieste GET per accedere ad una risorsa e richieste PUT, POST e DELETE per modificarla o cancellarla.

SOAP API - WSDL

Le SOAP API (Simple Object Access Protocol) sono servizi Web che si basano su un protocollo XML per definire il formato dei messaggi delle richieste e delle risposte. Il formato dei messaggi XML di SOAP viene solitamente definito tramite un file WSDL (Web Services Description Language) che specifica gli elementi e gli attributi consentiti nello scambio di messaggi. 

Il file WSDL è leggibile dalla macchina e utilizzato dai server che interagiscono tra loro per facilitare la comunicazione. 

Un file WSDL può potenzialmente descrivere un formato del messaggio di notevole complessità.
Questo è il motivo essenziale per il quale le REST API stanno soppiantando le SOAP API in tutte le applicazioni dove non necessita una comunicazione particolarmente strutturata, quindi dove si può anche fare a meno dell'XML.

RPC API

Le RPC API (Remote Procedure Call) sono servizi Web che chiamano un metodo su un server remoto fornendo un messaggio codificato in HTTP. Il formato del messaggio codificato potrebbe essere XML (API XML-RPC) o JSON (API JSON-RPC), in entrambi i casi via HTTP come altri servizi web. Queste API sono agnostiche rispetto la linguaggio di programmazione (Java, Python, C ++, ...) con cui viene realizzato il metodo remoto.

gRPC API

Le gRPC API, sviluppate da Google, sono servizi web simili alle RPC API basate su RPC. gRPC definisce i messaggi non in formato XML o JSON ma attraverso un buffer, specificato attraverso un file con estensione .proto. Il buffer.proto  consente di definire la struttura dei dati e il modo in cui serializzare i dati che devono essere consumati dal server ricevente. Il formato "protobuffer" è considerato più leggero efficiente rispetto ad XML.

GraphQL

Le GraphQL API sono servizi web sviluppati da Facebook che consentono un'interazione dinamica basata su un unico endpoint. La query GraphQL recupera solo i dati necessari, consentendo richieste e risposte veloci.

Async API

AsyncAPI è uno standard open source mirato alle architetture basate su eventi (Event Driven Architecture). Simile alla specifica OpenAPI, consente di definire un'interfaccia comune per le interfacce EDA e consente una gestione multicanale. Quindi la stessa specifica può essere utilizzata per un API basata su MQTT o per una API Kafka.

AsyncAPI si basa su due concetti:

  • i messaggi guidano la maggior parte delle interazioni API
  • questi messaggi descrivono azioni o eventi. 

In sostanza, AsyncAPI crede che tutto possa essere rappresentato come un sistema di messaggi, con un'intestazione e un payload facoltativi o non richiesti. In questa visione, AsyncAPI cerca di abilitare la definizione di API utilizzando definizioni basate sul canale indipendenti dal protocollo.

Librerie di API

Le "API basate su libreria", si riferiscono a librerie di codice (ad esempio, file JAR) che gli sviluppatori aggiungono direttamente ai loro progetti per fornire funzionalità aggiuntive tramite classi e metodi (nel caso di linguaggi ad oggetti come Java, .NET stack, C++) o altre funzioni che possono essere chiamate localmente. Con le API della libreria nativa, le funzioni sono incorporate localmente all'interno del codice per potenziare le operazioni realizzate dall'applicazione. Questo tipo di API sono strutturalmente diverse rispetto alle Web API che abbiamo elencato in precedenza.

Un esempio? OpenSSL API, cioè la più importante libreria crittografica open source.

----------------------------------------------

ABBIAMO FINITO? Ovviamente no. 

Ci sono altri tipi di API che potremmo dover documentare? Certo.

Allora diciamo che sono abbastanza confidente di avervi fornito "una mappa di base" per iniziare ad orientarvi rispetto alle caratteristiche generali delle API che attualmente coprono, ragionevolmente, il 90% dei casi che potreste dover gestire.

A presto.

Condividi


Articoli correlati per categorie



Categoria: , ,

Nessun commento:

Posta un commento