API (Application Programming Interface)

Un'API è il contratto attraverso cui un software ne invoca un altro, definendo operazioni, input, output e semantica degli errori. Una web API ben progettata è coerente, evolvibile ed esplicita su versioning e modalità di fallimento. REST, gRPC e GraphQL sono gli stili dominanti per le API di rete.

Affordance (Hypermedia)

Un'affordance è un'azione che un client può compiere su una risorsa, pubblicizzata dal server come link o form nella risposta invece di essere cablata nel client. Le API guidate da hypermedia (HATEOAS) espongono affordance affinché i client scoprano le transizioni disponibili a runtime. Questo disaccoppia il client dalla struttura degli URL del server, al costo di una logica client più complessa.

Bearer Token

Un bearer token è una credenziale il cui semplice possesso concede l'accesso, inviata nell'header Authorization: Bearer . Poiché chiunque lo detenga può usarlo, i bearer token devono viaggiare solo su TLS, essere a vita breve e non finire mai nei log. Gli access token OAuth 2.0 e i JWT sono usati comunemente come bearer token.

Compatibilità all'indietro

Una modifica di un'API è retrocompatibile se i client esistenti continuano a funzionare senza modifiche dopo il rilascio. Aggiungere campi opzionali, nuovi endpoint o una gestione tollerante degli enum è in genere sicuro; rimuovere o rinominare campi, o irrigidire la validazione, di solito rompe i client. Il Semantic Versioning codifica questa distinzione nella versione MAJOR.

Caching (HTTP)

Il caching HTTP permette di riutilizzare le risposte senza ricontattare l'origine, controllato da Cache-Control, Expires, ETag e Last-Modified. Una risposta marcata Cache-Control: public, max-age=3600 può essere conservata da cache condivise e private per un'ora. Un caching corretto riduce latenza e carico ma richiede attenta invalidazione e gestione di Vary.

Richiesta condizionale

Una richiesta condizionale applica un metodo HTTP solo se una precondizione è soddisfatta, usando header come If-None-Match (con un ETag) o If-Modified-Since. Alimenta il caching efficiente (un 304 Not Modified salta il body) e la concorrenza ottimistica (If-Match rifiuta un aggiornamento obsoleto con 412 Precondition Failed).

Content Negotiation

La content negotiation è il meccanismo con cui client e server concordano la rappresentazione di una risorsa, guidato dagli header di richiesta Accept, Accept-Language e Accept-Encoding e dall'header di risposta Content-Type. Un server può restituire JSON o XML per la stessa risorsa a seconda dell'header Accept, rispondendo 406 Not Acceptable se non può soddisfare la richiesta.

CORS è un meccanismo di sicurezza del browser che permette a un server di dichiarare quali altre origini possono leggere le sue risposte, tramite header come Access-Control-Allow-Origin. Per le richieste non semplici il browser invia prima una richiesta di preflight OPTIONS, e il server deve rispondere con i metodi e gli header consentiti. CORS protegge gli utenti, non il server, ed è applicato solo dai browser.

CRUD

CRUD sta per Create, Read, Update, Delete, le quattro operazioni di base sui dati persistenti, mappate in REST su POST, GET, PUT/PATCH e DELETE. È una scorciatoia utile per descrivere l'ambito di una risorsa REST. Non tutte le API sono CRUD; alcune sono modellate meglio come comandi o eventi.

Paginazione a cursore

La paginazione a cursore (keyset) restituisce una pagina di risultati più un cursore opaco che punta subito dopo l'ultimo elemento, che il client rimanda per ottenere la pagina successiva. A differenza della paginazione a offset resta corretta ed efficiente quando elementi vengono inseriti o eliminati tra le richieste, perché cerca per chiave di ordinamento stabile invece di saltare un conteggio di righe.

Deprecazione

La deprecazione è la segnalazione formale che un elemento dell'API verrà rimosso, dando ai client il tempo di migrare prima che sparisca. Gli header HTTP Deprecation e Sunset (RFC 9745 e RFC 8594) comunicano lo stato e la data di rimozione nelle risposte. Una deprecazione deve sempre accompagnarsi a un percorso di migrazione e a una tempistica documentata.

DELETE

DELETE è il metodo HTTP che richiede la rimozione della risorsa target. È idempotente: eliminare la stessa risorsa due volte lascia lo stesso stato finale, anche se la seconda chiamata di solito restituisce 404 Not Found mentre la prima 200 OK o 204 No Content. DELETE non è safe, perché modifica lo stato del server.

Endpoint

Un endpoint è un URL specifico più un metodo HTTP che un client può chiamare, ad esempio GET /v1/orders/{id}. Nel design orientato alle risorse gli endpoint espongono sostantivi (risorse) e usano i metodi HTTP come verbi. Raggruppare endpoint correlati sotto una gerarchia di path coerente è centrale per un'API scopribile.

ETag

Un ETag (entity tag) è un identificatore opaco che il server assegna a una specifica versione della rappresentazione di una risorsa, restituito nell'header ETag. I client lo usano in If-None-Match per la validazione della cache e in If-Match per la concorrenza ottimistica. Un ETag forte garantisce uguaglianza byte per byte; uno debole (prefisso W/) garantisce solo equivalenza semantica.

Fan-out / Aggregazione

Il fan-out è il pattern in cui una singola richiesta del client innesca chiamate a più servizi a valle, le cui risposte vengono aggregate in una sola. Un API gateway o un backend-for-frontend spesso esegue l'aggregazione per ridurre i round trip del client. Il rischio è che la latenza complessiva e la probabilità di fallimento crescano con il numero di chiamate a valle.

GET

GET è il metodo HTTP che recupera una rappresentazione della risorsa target senza modificarla. È sia safe (nessun effetto collaterale) sia idempotente, il che rende le risposte cacheabili e le richieste liberamente ripetibili. Un GET non deve mai portare un body di richiesta che influenzi il risultato né innescare cambiamenti di stato.

GraphQL

GraphQL è un linguaggio di query e un runtime per API in cui il client specifica esattamente quali campi gli servono in una sola richiesta a un unico endpoint, tipicamente POST /graphql. Elimina over- e under-fetching ma sposta la complessità sul server (analisi del costo delle query, risoluzione del problema N+1) e complica il caching HTTP, che è basato sugli URL.

gRPC

gRPC è un framework RPC ad alte prestazioni che usa HTTP/2 per il trasporto e i Protocol Buffers per la serializzazione tipizzata e binaria dei messaggi. Supporta chiamate unary e streaming e genera stub client/server da un contratto .proto. Eccelle nella comunicazione interna service-to-service a bassa latenza ma è meno adatto al browser rispetto a REST/JSON.

HATEOAS

HATEOAS (Hypermedia As The Engine Of Application State) è il vincolo REST per cui le risposte includono link che descrivono le azioni successive disponibili, così i client navigano l'API seguendo i link invece di costruire URL. È il vincolo REST meno adottato nella pratica. Ben realizzato consente al server di evolvere la struttura degli URL senza rompere i client.

Idempotenza

Un'operazione è idempotente se eseguirla più volte ha lo stesso effetto sullo stato del server di eseguirla una sola volta. GET, PUT e DELETE sono definiti idempotenti; POST in generale no. Per rendere ripetibile in sicurezza un'operazione di creazione non safe, i client inviano una chiave di idempotenza su cui il server deduplica.

Chiave di idempotenza

Una chiave di idempotenza è un valore univoco generato dal client (spesso un UUID) inviato in un header come Idempotency-Key affinché il server riconosca e ignori una richiesta ripetuta, restituendo il risultato originale invece di agire due volte. È essenziale per ritentare in sicurezza operazioni non idempotenti come i pagamenti dopo un timeout di rete. Il server memorizza la chiave e la sua prima risposta per una finestra limitata.

JSON:API

JSON:API è una specifica che standardizza il formato dei documenti JSON di richiesta e risposta, coprendo resource object, relazioni, dati inclusi, paginazione, filtraggio ed errori. Adottarla elimina le discussioni sul formato dell'envelope e dà ai client una struttura prevedibile. La sua rigidità può risultare pesante per semplici API interne.

JWT (JSON Web Token)

Un JWT è un token compatto, URL-safe, firmato (e opzionalmente cifrato) che porta claim come payload JSON, definito dalla RFC 7519. Le API usano i JWT firmati come access token stateless, verificando la firma invece di una lettura dal database. Poiché il payload è solo codificato in base64url (non cifrato di default), non inserire mai segreti in un JWT e valida sempre exp, iss e aud.

Media Type

Un media type (tipo MIME) etichetta il formato di una rappresentazione, ad esempio application/json o application/problem+json, trasportato in Content-Type e Accept. I media type vendor e versionati come application/vnd.example.v2+json abilitano il versioning basato su media type. Il media type dice al destinatario come interpretare il body.

OpenAPI

OpenAPI è una specifica indipendente dal linguaggio per descrivere le API HTTP in un documento leggibile dalla macchina (YAML o JSON), un tempo nota come Swagger. Da un solo documento OpenAPI i team generano documentazione, SDK client, stub server, mock server e contract test. Trattare il file OpenAPI come fonte di verità è il cuore di un workflow design-first.

OAuth 2.0

OAuth 2.0 è un framework di autorizzazione (RFC 6749) che permette a un'applicazione di terze parti di ottenere accesso limitato a una risorsa per conto di un utente senza condividerne le credenziali. Definisce flussi di grant come Authorization Code (con PKCE) per app rivolte all'utente e Client Credentials per l'accesso service-to-service. OAuth gestisce l'autorizzazione; l'autenticazione dell'utente si aggiunge con OpenID Connect.

Paginazione a offset

La paginazione a offset restituisce una finestra di risultati tramite i parametri limit e offset (o page e size), saltando offset righe prima di restituirne limit. È semplice e consente di saltare a una pagina arbitraria, ma diventa lenta su offset grandi e può saltare o duplicare righe quando i dati sottostanti cambiano tra le richieste.

PATCH

PATCH è il metodo HTTP che applica una modifica parziale a una risorsa, inviando solo i campi da cambiare invece di una rappresentazione completa. Non è garantito idempotente in generale, anche se un dato documento di patch può essere progettato per esserlo. I formati comuni sono JSON Merge Patch (RFC 7386) e JSON Patch (RFC 6902).

PUT

PUT è il metodo HTTP che crea o sostituisce integralmente la risorsa target con la rappresentazione nel body della richiesta. È idempotente: inviare lo stesso PUT ripetutamente produce lo stesso stato finale. Usa PUT quando il client controlla l'identificatore della risorsa e fornisce una rappresentazione completa; usa POST quando è il server ad assegnare l'identificatore.

POST

POST è il metodo HTTP che invia dati da elaborare alla risorsa target, più spesso per creare una risorsa subordinata sotto una collezione. Non è né safe né idempotente, quindi ripeterlo può creare duplicati a meno che non si usi una chiave di idempotenza. Una creazione riuscita di solito restituisce 201 Created con un header Location che punta alla nuova risorsa.

Problem Details (RFC 9457)

Problem Details è un formato JSON (e XML) standard per le risposte di errore HTTP, definito dalla RFC 9457 (che rende obsoleta la RFC 7807), con il media type application/problem+json. Un documento di problema porta i membri type, title, status, detail e instance più estensioni. Standardizzare gli errori permette ai client di gestire i fallimenti in modo uniforme tra API diverse.

Rate Limiting

Il rate limiting limita quante richieste un client può fare in una finestra temporale per proteggere un servizio da sovraccarico e abuso. I server segnalano i limiti con gli header RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset e rifiutano il traffico in eccesso con 429 Too Many Requests, idealmente includendo un header Retry-After. Token bucket e sliding window sono algoritmi comuni.

REST (Representational State Transfer)

REST è uno stile architetturale per applicazioni di rete definito da Roy Fielding, basato su vincoli tra cui client-server, statelessness, cacheabilità, interfaccia uniforme e sistema a livelli. Un'API RESTful modella risorse indirizzabili tramite URL e manipolate con metodi HTTP e rappresentazioni standard. Molte "REST API" soddisfano alcuni ma non tutti i vincoli, in particolare HATEOAS.

Risorsa

Una risorsa è qualsiasi entità con nome che un'API espone - un ordine, un utente, una collezione di fatture - identificata da un URI e manipolata tramite rappresentazioni. Nel design REST le risorse sono sostantivi e i metodi HTTP sono i verbi che agiscono su di esse. Modellare le risorse giuste e le loro relazioni è l'attività di design centrale.

Richardson Maturity Model

Il Richardson Maturity Model valuta un'API REST su tre livelli sopra la baseline: il Livello 1 introduce le risorse, il Livello 2 usa correttamente i verbi HTTP e gli status code, e il Livello 3 aggiunge i controlli hypermedia (HATEOAS). È un'euristica utile per valutare quanto un'API sia RESTful, anche se il livello 3 è raramente necessario nella pratica.

Metodo safe

Un metodo HTTP safe è uno che non modifica lo stato del server ed è inteso solo per il recupero, ossia GET, HEAD e OPTIONS. La sicurezza permette agli intermediari di mettere in cache e fare prefetch delle risposte liberamente. Un metodo che muta lo stato non deve mai essere esposto come safe, indipendentemente da come è chiamato.

Schema (API)

Uno schema di API è una descrizione formale e leggibile dalla macchina delle forme di richieste e risposte, come un JSON Schema, una sezione components di OpenAPI o un messaggio Protocol Buffers. Gli schema abilitano validazione, generazione di codice e contract test. Pubblicare e versionare lo schema trasforma un'API informale in un contratto verificabile.

SDK (Software Development Kit)

Un SDK è una libreria client che incapsula le chiamate HTTP di un'API dietro funzioni idiomatiche in un dato linguaggio, gestendo auth, retry, paginazione e serializzazione. Gli SDK migliorano la developer experience e possono essere generati da un documento OpenAPI. Il rischio è la divergenza tra SDK scritti a mano e il contratto dell'API.

Status Code

Uno status code HTTP è un numero di tre cifre nella risposta che segnala l'esito di una richiesta, raggruppato in 1xx informativo, 2xx successo, 3xx redirezione, 4xx errore del client e 5xx errore del server. Usare il codice semanticamente corretto (ad esempio 201, 400, 404, 409, 429) permette a client e intermediari generici di comportarsi correttamente. Usare 200 per gli errori rompe questo contratto.

Statelessness

La statelessness è il vincolo REST per cui ogni richiesta porta tutte le informazioni necessarie a elaborarla, senza stato di sessione del client conservato sul server tra una richiesta e l'altra. Permette a qualsiasi istanza di server di gestire qualsiasi richiesta, semplificando lo scaling orizzontale e il failover. Lo stato applicativo vive sul client o in store condivisi, non nella memoria del server.

Swagger UI

Swagger UI è uno strumento che rende un documento OpenAPI come documentazione interattiva e navigabile, dove gli sviluppatori possono leggere le definizioni degli endpoint ed eseguire richieste live "try it out". È comunemente servito insieme a un'API per fornire documentazione sempre aggiornata, derivata dal contratto. È uno dei tanti strumenti dell'ecosistema OpenAPI.

TLS (Transport Layer Security)

TLS è il protocollo crittografico che cifra e autentica il traffico HTTP, trasformando http in https. Le API devono essere servite esclusivamente su TLS affinché credenziali, token e payload non possano essere intercettati o manomessi. La pratica moderna impone TLS 1.2 o 1.3 e rifiuta l'HTTP in chiaro, spesso tramite HSTS.

Throttling

Il throttling è l'atto di rallentare o rifiutare deliberatamente le richieste quando un client supera un'allocazione, il lato applicativo del rate limiting. Un client sottoposto a throttling riceve 429 Too Many Requests e dovrebbe fare backoff, idealmente onorando l'header Retry-After. Un throttling garbato protegge la capacità condivisa e garantisce accesso equo sotto carico.

Versioning su URI

Il versioning su URI codifica la versione dell'API nel path, ad esempio /v1/orders, rendendo la versione esplicita e facile da instradare e mettere in cache. È lo schema di versioning più comune perché è visibile e non ambiguo, al costo di cambiare ogni URL a un bump major. Le alternative includono il versioning via header e via media type.

Webhook

Un webhook è una callback HTTP server-to-server: invece che il client faccia polling per i cambiamenti, l'API invia un evento a un URL fornito dal client quando qualcosa accade. I webhook robusti includono una firma (es. HMAC) per la verifica, retry con backoff e un ID evento per un consumo idempotente. Invertono la direzione abituale della richiesta e richiedono al ricevente di esporre un endpoint.

429 Too Many Requests

429 Too Many Requests è lo status code HTTP che un server restituisce quando un client ha inviato troppe richieste in una data finestra temporale, la risposta standard a una violazione del rate limit. Dovrebbe includere un header Retry-After che indica al client quando riprovare. I client dovrebbero trattare il 429 come segnale di fare backoff, non di insistere.