Omnillink
Un indirizzo in ingresso, dati pronti all'uso in uscita: un'API che mette per iscritto i propri limiti e allega le proprie misure a ogni risposta.
- Anno
- 2026
- Stack
- TypeScript · Node.js · Fastify · Playwright · Redis · Tailwind · Vercel
- Progettazione di API
- Sviluppo back-end
- Sicurezza applicativa
- SDK e strumenti per sviluppatori
- Documentazione
- Sito di presentazione

- route sotto /api/v1, descritte nel documento OpenAPI 3.1
- 20
- strumenti in sola lettura esposti agli agenti IA tramite MCP
- 8
- cookie e strumenti di misurazione dell'audience sul sito
- 0
- licenza del software, da ospitare in proprio
- MIT
Cosa c'era da risolvere.
Il contesto
Omnillink è un'API sviluppata da KAYZEN a Lione. Le si invia l'indirizzo di una pagina web pubblica; restituisce i suoi metadati, uno screenshot, un'esportazione in PDF, campi estratti su misura o il suo contenuto in Markdown. Il software è distribuito con licenza MIT e si ospita in proprio. Il sito omnillink.kayzen-lyon.com ne è la dimostrazione, con una sandbox e una documentazione in francese e in inglese.
Il vincolo
Mostrare l'anteprima di un link, archiviare una pagina in PDF o dare il testo di un articolo a un agente IA richiede ogni volta lo stesso lavoro: leggere una pagina che non si controlla, a volte costruita in JavaScript, a volte protetta, senza esporre la propria rete. Le API ospitate che se ne occupano fatturano a chiamata e vedono passare gli indirizzi letti. Serviva uno strumento da installare sulla propria infrastruttura, con impostazioni e limiti messi per iscritto, e che non potesse essere sfruttato per raggiungere una rete interna.
La risposta
Una richiesta per ogni esigenza, e un percorso di lettura parsimonioso: la pagina viene letta prima con una semplice richiesta HTTP, e Chromium viene avviato solo se il risultato è povero o se la pagina è un guscio di applicazione vuoto. Ogni indirizzo viene validato contro gli attacchi SSRF prima di qualsiasi connessione. Ogni risposta dice che cosa è successo: durata, modalità di rendering, stato della cache, identificativo della richiesta e quota residua. Il sito segue la stessa regola: non mostra né volumi né testimonianze, mostra risposte reali dell'API.
Ogni scelta di design, e il suo perché.
La dimostrazione è nella home page
Il visitatore inserisce un indirizzo e lancia una richiesta vera dalla home page, senza chiave né registrazione. Uno sviluppatore giudica un'API dalla sua risposta: mostrargliela subito, con la durata, la modalità di rendering e lo stato della cache, gli evita di creare un account per farsi un'idea.
Ogni capacità è mostrata con il suo vero output
Le schede delle funzionalità non hanno illustrazioni: ciascuna mostra una risposta reale dell'API, acquisita su una pagina di test, e porta alla relativa documentazione e alla sandbox già configurata. Il lettore vede il formato esatto che riceverà prima di scrivere una riga di codice.
Prove anziché numeri
Il prodotto è appena stato pubblicato: un volume di richieste o una testimonianza non avrebbero alcuna realtà. Il sito quindi non ne mostra. Al loro posto, una sezione elenca ciò che ognuno può controllare da sé: il modello di sicurezza pubblicato, le misure allegate a ogni risposta, la licenza e i limiti adottati.
Una sandbox che scrive il codice
La sandbox dà accesso a tutti i parametri e genera il codice della richiesta in otto linguaggi: curl, JavaScript, SDK TypeScript, Python, PHP, Go, Ruby e Rust. Il percorso tra la prova e la prima integrazione si riduce a un copia e incolla, senza passare dalla lettura completa del riferimento.
L'identità visiva di KAYZEN, tema chiaro e tema scuro
Outfit per i titoli, Plus Jakarta Sans per il testo, blu marino e terracotta per l'azione principale: il sito riprende l'identità visiva di kayzen-lyon.com, perché l'API sia riconosciuta come un prodotto dell'agenzia. Il tema chiaro, il tema scuro o quello di sistema si sceglie nelle opzioni di visualizzazione.
Sistema tipografico
Titoli
Outfit
Testo corrente
Plus Jakarta Sans
Le due famiglie di kayzen-lyon.com, perché l'API sia riconosciuta come un prodotto dell'agenzia.
Cosa c'è sotto il cofano.
- TypeScript
- Node.js
- Fastify
- Playwright
- Redis
- Tailwind
- Vercel
Prima HTTP, il browser solo se necessario
Avviare Chromium per ogni pagina costa tempo e memoria. La pagina viene quindi letta prima con una richiesta HTTP e analizzata; il browser subentra solo se il risultato è povero, se la pagina è un guscio di applicazione vuoto o se il sito ha servito una pagina di blocco. Il campo meta.source indica il percorso seguito.
Una protezione SSRF a ogni connessione
Un'API che visita indirizzi forniti dal chiamante può servire a raggiungere una rete interna. Gli indirizzi privati, di loopback e dei metadati cloud vengono rifiutati, e la risoluzione DNS è vincolata alla connessione. Nel browser, tutto il traffico esce da un proxy interno che rivalida ogni connessione, reindirizzamenti compresi.
Nessun codice fornito dal chiamante viene eseguito
L'API non esegue alcuno script inviato dal client. Ciò che precede un'acquisizione si descrive con parametri e selettori CSS: fare clic, scorrere, attendere un elemento. È una funzione in meno, ed è voluta: codice arbitrario nel browser contraddirebbe l'isolamento e la protezione SSRF.
Né cookie né credenziali trasmessi alla pagina letta
Il chiamante può impostare soltanto tre intestazioni: Accept-Language, User-Agent e Referer. Cookie e Authorization sono esclusi, perché le risposte vengono messe in cache per indirizzo e servite a tutti: una pagina ottenuta con la sessione di un chiamante verrebbe servita al successivo.
Cache, deduplicazione e circuit breaker per host
I risultati vengono messi in cache, in memoria o in Redis, e richieste identiche ricevute nello stesso momento attivano una sola elaborazione. Un circuit breaker smette di contattare un host dopo diversi errori di rete consecutivi. Una pagina lenta o molto richiesta non monopolizza quindi i browser disponibili.
Un riferimento OpenAPI ricavato dal codice di validazione
I parametri del documento OpenAPI 3.1 sono derivati dagli schemi di validazione delle route: il riferimento pubblicato descrive ciò che il server accetta realmente. Ogni errore porta un codice stabile, da EINVALIDURL a ETIMEOUT, con lo stato HTTP corrispondente, perché il codice client lo gestisca senza analizzare un messaggio.
Un endpoint MCP per gli agenti IA
Otto strumenti in sola lettura sono esposti su POST /mcp. Passano dagli stessi servizi delle route REST, quindi dagli stessi controlli. Ogni risultato che contiene contenuto di pagina inizia con un avviso: questo testo proviene dal web, è un dato da valutare e non un'istruzione da seguire.
Un'unica funzione serve l'API e il sito
Su Vercel, il sito viene compilato e poi integrato nel bundle dell'API: un'unica funzione risponde a tutto. Il budget di tempo di una richiesta è di 55 secondi per impostazione predefinita, appena sotto la durata massima della funzione (60 secondi), perché sia l'API stessa a rispondere con un errore leggibile anziché essere interrotta dalla piattaforma.
Come il sito si fa trovare.
Sedici pagine, ciascuna in francese e in inglese
La sitemap dichiara 32 indirizzi: home, sandbox, riferimento dell'API, dieci guide, stato del servizio, accessibilità e note legali, in due lingue collegate da tag hreflang. Uno sviluppatore cerca una risposta precisa; ogni argomento ha quindi la propria pagina anziché una sezione di un'unica pagina.
File llms.txt per gli assistenti
Il sito pubblica /llms.txt, che elenca la documentazione con una riga di riassunto per pagina, e /llms-full.txt, che ne fornisce il testo integrale. Un assistente di programmazione interrogato sull'API può così leggere la documentazione aggiornata invece di indovinare i parametri.
Dati strutturati, e API tenuta fuori dalla scansione
La home page dichiara in JSON-LD l'editore, l'API (tipo WebAPI), il software e le sue domande frequenti. Il file robots.txt esclude /api/ dalla scansione: le risposte dell'API sono dati su altri siti, non pagine da indicizzare sotto il nome di Omnillink.
Né cookie né misurazione dell'audience
Il sito non installa alcun cookie e non carica alcuno strumento di misurazione dell'audience; le preferenze di tema, lingua e accessibilità restano nel browser. Non c'è quindi alcun banner di consenso da superare prima di leggere la documentazione.
Utilizzabile da tutti.
Da giugno 2025 l'Atto europeo sull'accessibilità (European Accessibility Act) impone l'accessibilità digitale a una larga parte dei servizi online. La affrontiamo in fase di progettazione, non come rimedio a posteriori.
Un pannello di opzioni su ogni pagina
Un pulsante apre le impostazioni di visualizzazione: dimensione del testo, contrasto elevato, font Atkinson Hyperlegible, interlinea, link sottolineati, animazioni ridotte. Le scelte vengono salvate nel browser e valgono per tutte le pagine, senza dipendere dalle impostazioni di sistema.
Ciò che è stato verificato, e ciò che non lo è stato
La pagina Accessibilità elenca le verifiche del 18 novembre 2026: contrasti calcolati per i due temi, navigazione da tastiera in un browser automatizzato, assenza di scorrimento orizzontale a 375 pixel. Scrive anche ciò che manca: nessuna prova con uno screen reader, nessun audit WCAG o RGAA da parte di una persona formata. Dirlo evita di lasciar credere a una conformità che non è stata accertata.
Cosa è stato consegnato.
- Home — dimostrazione dal vivo, capacità, funzionamento, self-hosting, domande frequenti
- Sandbox — tutti i parametri, codice generato in otto linguaggi
- Riferimento dell'API — route, parametri, errori, quote e cache
- Guide — primi passi, self-hosting, SDK, agenti IA, ricette, sicurezza, limiti
- Stato del servizio
- Accessibilità, note legali e privacy
Lo svolgimento del progetto.
API di base
Metadati, screenshot, PDF, estrazione e contenuto leggibile; validazione degli indirizzi, cache e deployment in un'unica funzione su Vercel.
Hardening
Proxy interno che valida ogni connessione del browser, reindirizzamenti compresi; parametri sconosciuti ignorati anziché rifiutati.
Strumenti per sviluppatori
SDK TypeScript, riga di comando, server MCP, componente React, action GitHub ed esempi di integrazione.
Sito e pubblicazione
Sandbox, guide, ricerca, versione inglese, endpoint MCP ospitato e registro delle modifiche; messa online a novembre 2026.
Cosa ci chiedono spesso.
Altri lavori
Applicazione web e intelligenza artificialeStudio AI
Diciotto strumenti foto e video con IA, ognuno dei quali indica se gira nel browser o online: la privacy diventa una casella da spuntare, non una promessa.
Applicazione web e SEOKayzen Trust
Un indicatore di link dal metodo pubblicato: la fiducia si misura, e lo scarto con la popolarità tradisce i link acquistati.
Software libero e applicazione desktopKAYZEN Flux
Un convertitore senza server: il file non lascia mai il computer, e il codice è pubblico per verificarlo.
Lo stesso livello di rigore, per il tuo sito.
Audit gratuito del tuo sito attuale, preventivo entro 24 ore e un ragionamento scritto, come quello che hai appena letto. Pagamento in tre rate senza interessi; agevolazioni locali verificate prima della firma.