API

API sta per Application Programming Interface, il contratto che permette a un programma di invocarne un altro, definendone operazioni, input, output ed errori. Nel contesto web indica di solito un'API HTTP consumata sulla rete. È l'unità attorno a cui è costruito un kit come questo.

REST

REST sta per Representational State Transfer, lo stile architetturale introdotto da Roy Fielding per i sistemi ipermediali distribuiti. I suoi vincoli (client-server, stateless, cacheable, interfaccia uniforme, a livelli) plasmano gran parte delle API HTTP moderne. "RESTful" indica di solito l'orientamento alle risorse su HTTP, anche quando HATEOAS è omesso.

RPC

RPC sta per Remote Procedure Call, uno stile in cui il client invoca una procedura con nome su un server remoto come se fosse locale. gRPC e JSON-RPC sono stili RPC, in contrasto con l'orientamento alle risorse di REST. RPC mappa naturalmente su azioni e comandi invece che su sostantivi.

CRUD

CRUD sta per Create, Read, Update, Delete, le quattro operazioni canoniche sui dati memorizzati. In REST corrispondono a POST, GET, PUT/PATCH e DELETE. Il termine descrive l'ambito di molti servizi centrati sulle risorse.

HTTP

HTTP sta per HyperText Transfer Protocol, il protocollo a livello applicativo di richiesta/risposta che sta alla base delle web API. La sua semantica attuale è definita dalla RFC 9110, mentre HTTP/1.1, HTTP/2 e HTTP/3 differiscono nel trasporto. Metodi, status code e header sono il vocabolario di HTTP.

HATEOAS

HATEOAS sta per Hypermedia As The Engine Of Application State, il vincolo REST per cui le risposte portano link alle azioni valide successive. I client navigano allora seguendo i link invece di cablare gli URL. È il livello 3 di REST nel Richardson Maturity Model.

CORS

CORS sta per Cross-Origin Resource Sharing, il meccanismo del browser che permette a un server di consentire letture cross-origin delle sue risposte. Si basa sugli header Access-Control-Allow-* e, per le richieste non semplici, su una chiamata di preflight OPTIONS. CORS è applicato dai browser, non dal server stesso.

JWT

JWT sta per JSON Web Token, un token compatto e firmato che porta claim come JSON, definito dalla RFC 7519. Le API lo usano come credenziale bearer stateless verificata tramite firma. Il suo payload è codificato, non cifrato, quindi non deve mai contenere segreti.

OAuth

OAuth (2.0) è un framework di autorizzazione, RFC 6749, che concede a una terza parte accesso limitato a una risorsa per conto di un utente senza condividerne le credenziali. Definisce flussi come Authorization Code con PKCE e Client Credentials. L'autenticazione si aggiunge tramite OpenID Connect.

OIDC

OIDC sta per OpenID Connect, un livello di identità costruito sopra OAuth 2.0 che aggiunge l'autenticazione e un ID token. Dove OAuth risponde a "cosa può fare questa app", OIDC risponde a "chi è l'utente". Standardizza gli endpoint di user info e discovery.

TLS

TLS sta per Transport Layer Security, il protocollo che cifra e autentica HTTP, producendo HTTPS. Le API dovrebbero accettare solo traffico TLS 1.2+. Protegge credenziali e payload da intercettazione e manomissione.

mTLS

mTLS sta per mutual TLS, dove sia il client sia il server presentano e verificano i certificati, non solo il server. È comune per l'autenticazione service-to-service in una rete zero-trust. Elimina la necessità di scambiare bearer token tra servizi fidati.

ETag

ETag sta per entity tag, un identificatore di versione opaco per la rappresentazione di una risorsa, restituito nell'header ETag. Guida la validazione della cache tramite If-None-Match e la concorrenza ottimistica tramite If-Match. Gli ETag forti implicano uguaglianza di byte; quelli deboli (W/) implicano equivalenza semantica.

URI

URI sta per Uniform Resource Identifier, la stringa che dà un nome a una risorsa, di cui un URL è la forma localizzante. REST indirizza le risorse tramite URI e agisce su di esse con i metodi HTTP. URI stabili e prevedibili sono un segno distintivo di un buon design di API.

URL

URL sta per Uniform Resource Locator, un URI che identifica e localizza una risorsa sulla rete. Gli endpoint di un'API sono URL che combinano una base, un path e parametri di query opzionali. Il caching HTTP è basato sull'URL.

MIME

MIME sta per Multipurpose Internet Mail Extensions, l'origine del sistema di media type usato in Content-Type e Accept. Valori come application/json e application/problem+json dicono ai destinatari come interpretare un body. I tipi vendor come application/vnd.api+json supportano versioning e specifiche.

SDK

SDK sta per Software Development Kit, qui una libreria client, generata o scritta a mano, che incapsula un'API in chiamate idiomatiche di linguaggio. Gli SDK gestiscono auth, retry, paginazione e serializzazione per i consumatori. Possono essere generati da un documento OpenAPI per restare allineati.

CRUD vs RPC

Questo accostamento contrappone il design orientato alle risorse (CRUD sui verbi HTTP) a quello orientato alle azioni (procedure con nome). REST predilige i sostantivi; RPC predilige i verbi. Molte API reali sono ibride, esponendo risorse più qualche endpoint in stile comando.

RFC

RFC sta per Request for Comments, la serie di documenti IETF che definisce gli standard internet tra cui HTTP (RFC 9110), JWT (RFC 7519), OAuth (RFC 6749) e Problem Details (RFC 9457). Citare il numero di RFC fissa una definizione precisa e versionata. Il design delle API si appoggia fortemente a questi standard.

CQRS

CQRS sta per Command Query Responsibility Segregation, la separazione del modello usato per modificare i dati (comandi) da quello usato per leggerli (query). Sulla superficie dell'API può significare endpoint distinti di scrittura e lettura, o persino servizi distinti. Aggiunge complessità giustificata solo quando i carichi di lettura e scrittura divergono.

BFF

BFF sta per Backend For Frontend, un livello di API su misura per le esigenze di uno specifico client (web, mobile) che aggrega e rimodella i servizi a valle. Riduce l'over-fetching e i round trip del client. Ogni frontend ottiene un'API modellata per sé invece di un gateway uguale per tutti.

API Gateway

Un API gateway è un singolo punto d'ingresso che instrada le richieste ai servizi backend e centralizza le preoccupazioni trasversali: autenticazione, rate limiting, terminazione TLS e rimodellamento delle richieste. Disaccoppia i client dalla topologia interna. Sovraccaricarlo di logica di business, però, lo trasforma in un collo di bottiglia.

SLA

SLA sta per Service Level Agreement, l'impegno contrattuale sulla disponibilità e le prestazioni di un'API (es. 99,9% di uptime). È sostenuto da SLO e SLI misurabili. I rate limit e gli error budget sono spesso espressi in relazione allo SLA.

SLO

SLO sta per Service Level Objective, un obiettivo interno per una metrica di affidabilità come la latenza p99 o il tasso di successo. È il traguardo ingegneristico che sostiene lo SLA promesso all'esterno. Violare uno SLO innesca la risposta operativa prima che lo SLA sia a rischio.

Latenza p99

La latenza p99 è il 99esimo percentile dei tempi di risposta: il 99% delle richieste si completa più velocemente di questo valore. La latenza di coda come p99 conta più della media per l'esperienza utente e per le chiamate fan-out. Gli SLO delle API sono spesso espressi come soglie p95 e p99.

PKCE

PKCE sta per Proof Key for Code Exchange, un'estensione di OAuth 2.0 (RFC 7636) che protegge il flusso Authorization Code dall'intercettazione, in origine per client mobile e SPA. Il client invia un code challenge hashato e in seguito il verifier. Ora è raccomandato per tutti i flussi Authorization Code.

HMAC

HMAC sta per Hash-based Message Authentication Code, un hash con chiave usato per firmare i payload affinché un destinatario possa verificarne integrità e origine. I webhook includono comunemente un header di firma HMAC calcolato sul body con un segreto condiviso. Il ricevente ricalcola e confronta per autenticare la chiamata.

DTO

DTO sta per Data Transfer Object, un oggetto piatto che trasporta dati attraverso un confine senza comportamento. I body di richiesta e risposta delle API sono DTO che disaccoppiano il contratto pubblico dal modello di dominio interno. Tenerli distinti evita che cambiamenti interni trapelino ai client.

2xx / 4xx / 5xx

Indicano le classi degli status code HTTP: 2xx per il successo, 4xx per gli errori del client (il chiamante deve cambiare qualcosa) e 5xx per gli errori del server (il server ha fallito). Scegliere la classe giusta permette a client e proxy generici di reagire correttamente. Restituire 200 con un body di errore rompe questo contratto.