Categoria

Pagina 1 di 2

API Design: interfacce che reggono l'integrazione reale, non la demo

Un'API è un contratto: una volta che qualcuno la usa, cambiarla costa. Progettarla bene significa pensare fin dall'inizio a versioning, gestione degli errori, sicurezza e documentazione, non aggiungerli dopo quando i problemi sono già in produzione e i client a valle già rotti. In questa categoria raccolgo il metodo con cui si costruisce un'API destinata a essere integrata sul serio.

Il primo tema è il contratto e i suoi standard. Una buona API parla un linguaggio prevedibile: gestione strutturata degli errori secondo Problem Details, documentazione generata dal codice con OpenAPI così che non diverga mai dall'implementazione, versioning pensato per far evolvere l'interfaccia senza rompere chi la usa. Sono le fondamenta che distinguono un'integrazione che dura da una che genera ticket a ogni rilascio.

Il secondo tema è la tenuta sotto integrazione reale: rate limiting per difendersi dagli scraper senza penalizzare i client legittimi, API gateway per centralizzare autenticazione e routing, webhook con delivery garantita e retry, load test che mettono alla prova l'API prima del go-live. E il fronte nuovo, dove le API incontrano l'AI: output strutturato validato, content negotiation per servire gli agenti, governance dei costi e degli abusi quando dall'altra parte non c'è più un browser ma un modello.

Se stai progettando o consolidando delle API, vedi l'integrazione di sistemi e AI o scrivimi.

Un'API ben progettata la capisci senza leggere la documentazione. Quella mal progettata non la capisci nemmeno leggendola.

OIDC spiegato con Zitadel: organizzazioni, progetti, grant e audience

OIDC spiegato con Zitadel: organizzazioni, progetti, grant e audience Chi arriva a Zitadel da Keycloak o da Auth0 sbaglia quasi sempre lo stesso passaggio: tratta l'applicazione come il confine di fiducia. Non lo è. Il confine è il progetto, e la conseguenza finisce dentro l'audience del token, dove trovi un identificativo diverso da quello che ti aspetti. Il modello mentale completo, da istanza e organizzazione fino ai grant e agli scope riservati, più il costo di accorgersi tardi di aver sbagliato i confini. Primo di tredici articoli su un'integrazione vera. Continua a leggere
Ultima modifica:

Rate limiting avanzato in Laravel 12: proteggere API e form da abusi

Rate limiting avanzato in Laravel 12: proteggere API e form da abusi Un endpoint di ricerca senza throttling è un invito: nel mio lavoro su API Laravel ad alto traffico ho visto scraper distribuiti saturare i worker PHP-FPM restando sempre sotto soglia per singolo IP. In questa guida costruisco, passo dopo passo, una strategia di rate limiting per Laravel 12 che parte dalle tre domande giuste: chi stai contando, su quale finestra, e cosa succede a chi sfora?. Continua a leggere
Ultima modifica:

Analisi architetturale di un evento "Click Day": deconstructing del caso studio "Bonus Vesta"

Analisi architetturale di un evento "Click Day": deconstructing del caso studio "Bonus Vesta" Un Click Day è il banco di prova più crudele per un'architettura web: migliaia di utenti che premono lo stesso bottone nello stesso istante, un picco che cresce di ordini di grandezza in pochi secondi e poi svanisce. Ho analizzato da cittadino e da ingegnere un Click Day reale che ha retto senza disservizi, ricostruendone l'architettura dai log di rete. Questa è la deconstruction tecnica di come ci è riuscito e di cosa insegna a chi deve reggere un picco improvviso. Continua a leggere
Ultima modifica:

Cloudflare, Coinbase e Lightning hanno appena resuscitato HTTP 402 dopo 29 anni di oblio: ecco come far pagare gli agenti AI che scrapano il tuo sito con Laravel, Symfony e PHP vanilla

Cloudflare, Coinbase e Lightning hanno appena resuscitato HTTP 402 dopo 29 anni di oblio: ecco come far pagare gli agenti AI che scrapano il tuo sito con Laravel, Symfony e PHP vanilla HTTP 402 Payment Required è stato 'reserved for future use' dal 1997. Nel 2026 Cloudflare, Coinbase (x402), Lightning Labs (L402) e Google (AP2) lo hanno finalmente resuscitato per far pagare gli agenti AI che scrapano il web. Ti racconto come ho implementato il pattern nel mio laboratorio personale con Laravel 12, Symfony 7 e PHP vanilla, con numeri reali di 14 giorni di esercizio e la realtà dietro l'hype. Continua a leggere
Ultima modifica:

Servire text/markdown agli agenti AI senza Cloudflare: content negotiation RFC 9110 on-origin con Laravel, Symfony e PHP vanilla

Servire text/markdown agli agenti AI senza Cloudflare: content negotiation RFC 9110 on-origin con Laravel, Symfony e PHP vanilla Claude Code, Cursor e OpenCode mandano già Accept: text/markdown e pagano -80% sui token. Cloudflare ha lanciato 'Markdown for Agents' ma non è l'unica via: implementare la content negotiation RFC 9110 direttamente on-origin ti dà controllo totale senza dipendenze edge. Ti mostro come farlo da Laravel 12, Symfony 7 e PHP vanilla, evitando il falso cloaking di cui parla Mueller. Continua a leggere
Ultima modifica:

Integrazione con sistemi ERP legacy tramite API PHP: pattern e insidie comuni

Integrazione con sistemi ERP legacy tramite API PHP: pattern e insidie comuni Ho integrato quattro gestionali italiani diversi con applicazioni Laravel: ognuno aveva una API SOAP degli anni 2000 con documentazione parziale e comportamenti non documentati. Vi racconto il pattern adapter che uso per isolare l'integrazione dal codice applicativo e come gestire le incongruenze dei dati tra sistemi. Continua a leggere
Ultima modifica:

Go come inference gateway per LLM: perché Golang vince su PHP e Node quando la latenza conta davvero

Go come inference gateway per LLM: perché Golang vince su PHP e Node quando la latenza conta davvero PHP e Node sono ottimi per la logica di dominio, ma come inference gateway per LLM sotto carico soffrono: event loop Node saturabile con chiamate lente, PHP-FPM worker-bound con decine di secondi di attesa per token streaming. Go risolve entrambi: concorrenza nativa con goroutine, latenza sub-10ms sui routing decision, gestione elegante di streaming SSE verso migliaia di client paralleli. Ti mostro l'architettura gateway Go che ho costruito come front-end unificato per modelli LLM eterogenei. Continua a leggere
Ultima modifica:

Costruire API webhook robuste in Laravel: delivery garantita, retry e sicurezza

Costruire API webhook robuste in Laravel: delivery garantita, retry e sicurezza Un sistema di webhook che invia notifiche a 200 integratori terzi non può permettersi delivery inaffidabile. Ho costruito un sistema con coda prioritaria, retry esponenziale fino a 24 ore, firma HMAC per autenticità, logging di ogni tentativo e dashboard di monitoring per gli integratori. Zero delivery perse da 9 mesi. Continua a leggere
Ultima modifica:

Strumenti utili per le API

Tool gratuiti per progettare e testare API:

JWT decoder, JSON formatter, Codici di stato HTTP, Convertitore cURL in codice.