Applicazione web e API per sviluppatori

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
https://omnillink.kayzen-lyon.com/
Home page del sito Omnillink — Applicazione web e API per sviluppatori, realizzato da KAYZEN
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
Il punto di partenza

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.

Design e direzione artistica

Ogni scelta di design, e il suo perché.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

Ingegneria

Cosa c'è sotto il cofano.

  • TypeScript
  • Node.js
  • Fastify
  • Playwright
  • Redis
  • Tailwind
  • Vercel
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

Posizionamento SEO

Come il sito si fa trovare.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

Accessibilità

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.

  1. 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.

  2. 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.

Struttura del sito

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
Metodo

Lo svolgimento del progetto.

  1. API di base

    Metadati, screenshot, PDF, estrazione e contenuto leggibile; validazione degli indirizzi, cache e deployment in un'unica funzione su Vercel.

  2. Hardening

    Proxy interno che valida ogni connessione del browser, reindirizzamenti compresi; parametri sconosciuti ignorati anziché rifiutati.

  3. Strumenti per sviluppatori

    SDK TypeScript, riga di comando, server MCP, componente React, action GitHub ed esempi di integrazione.

  4. Sito e pubblicazione

    Sandbox, guide, ricerca, versione inglese, endpoint MCP ospitato e registro delle modifiche; messa online a novembre 2026.

Domande

Cosa ci chiedono spesso.

Il software è distribuito con licenza MIT: lo si può usare, modificare e ospitare in proprio, senza costi per richiesta oltre al proprio hosting. L'istanza che serve il sito è una dimostrazione, con un limite di frequenza.

No. L'API risponde senza autenticazione. L'intestazione facoltativa x-api-key alza il limite di frequenza, e le chiavi sono definite dal gestore di ciascuna istanza. Per impostazione predefinita, il limite è di 60 richieste per finestra senza chiave e di 600 con una chiave.

Le pagine pubbliche in http o https. Gli indirizzi privati, locali o interni vengono rifiutati dalla protezione SSRF. Le pagine costruite in JavaScript vengono renderizzate in Chromium quando è necessario. Se un sito risponde con una pagina di blocco, l'API lo segnala con un errore invece di restituire quella pagina come contenuto.

Node.js 22 o successivo, e Chromium, installato da Playwright. Redis è facoltativo: senza, la cache e i contatori di quota vivono in memoria, istanza per istanza. La gestione resta a carico di chi ospita: aggiornamenti, Chromium, monitoraggio.

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.

Condividi