Omnillink
주소 하나가 들어가면 바로 쓸 수 있는 데이터가 나옵니다: 스스로의 한계를 문서로 밝히고, 모든 응답에 측정값을 함께 싣는 API입니다.
- 연도
- 2026
- 기술 스택
- TypeScript · Node.js · Fastify · Playwright · Redis · Tailwind · Vercel
- API 설계
- 백엔드 개발
- 애플리케이션 보안
- 개발자용 SDK와 도구
- 문서
- 소개 사이트

- 개의 /api/v1 라우트, OpenAPI 3.1 문서에 기술
- 20
- 개의 읽기 전용 도구, MCP로 AI 에이전트에 제공
- 8
- 사이트의 쿠키와 방문자 분석 도구
- 0
- 소프트웨어 라이선스, 자체 호스팅
- MIT
해결해야 했던 과제.
배경
Omnillink는 KAYZEN이 리옹에서 만들어 제공하는 API입니다. 공개된 웹 페이지의 주소를 보내면 그 페이지의 메타데이터, 스크린샷, PDF 내보내기, 맞춤 추출한 필드, 또는 Markdown 형식의 콘텐츠를 돌려줍니다. 소프트웨어는 MIT 라이선스로 배포되며 자체 호스팅해 사용합니다. omnillink.kayzen-lyon.com 사이트는 그 데모로, 샌드박스와 프랑스어·영어 문서를 갖추고 있습니다.
제약
링크 미리보기를 표시하거나, 페이지를 PDF로 보관하거나, 기사 본문을 AI 에이전트에 넘기려면 매번 같은 작업이 필요합니다. 내가 통제하지 않는 페이지, 때로는 JavaScript로 만들어지고 때로는 보호된 페이지를, 자신의 네트워크를 노출하지 않고 읽어야 합니다. 이 일을 대신해 주는 호스팅형 API는 호출마다 요금을 받고, 읽는 주소도 그 사업자가 보게 됩니다. 필요한 것은 자신의 환경에 설치할 수 있고, 설정과 한계가 문서로 적혀 있으며, 내부 네트워크에 접근하는 데 악용될 수 없는 도구였습니다.
해법
필요 하나에 요청 하나, 그리고 낭비 없는 읽기 경로를 택했습니다. 페이지는 먼저 단순한 HTTP 요청으로 읽고, 결과가 빈약하거나 페이지가 빈 애플리케이션 셸일 때에만 Chromium을 실행합니다. 모든 주소는 연결에 앞서 SSRF 공격에 대비해 검증됩니다. 모든 응답은 무슨 일이 있었는지 알려 줍니다. 소요 시간, 렌더링 방식, 캐시 상태, 요청 식별자, 남은 할당량입니다. 사이트도 같은 원칙을 따릅니다. 이용량도 고객 후기도 내세우지 않고, API의 실제 응답을 보여 줍니다.
모든 선택에는 이유가 있습니다.
데모는 홈 페이지에
방문자는 홈 페이지에서 주소를 입력하고, 키도 가입도 없이 실제 요청을 실행합니다. 개발자는 API를 응답으로 판단합니다. 소요 시간, 렌더링 방식, 캐시 상태와 함께 응답을 바로 보여 주면, 어떤 도구인지 가늠하려고 계정을 만들 필요가 없습니다.
모든 기능을 실제 출력과 함께
기능 카드에는 일러스트가 없습니다. 카드마다 테스트 페이지에서 받아 둔 API의 실제 응답을 보여 주고, 해당 문서와 이미 설정된 샌드박스로 연결합니다. 읽는 사람은 코드를 한 줄 쓰기도 전에 자신이 받게 될 정확한 형식을 확인합니다.
숫자보다 증거
이 제품은 막 공개되었습니다. 요청 건수나 고객 후기를 내세워도 실체가 없습니다. 그래서 사이트에는 싣지 않았습니다. 그 대신 누구나 직접 확인할 수 있는 것을 한 섹션에 나열했습니다. 공개된 보안 모델, 모든 응답에 함께 담기는 측정값, 라이선스, 채택한 한계입니다.
코드를 써 주는 샌드박스
샌드박스에서는 모든 매개변수를 다룰 수 있고, 요청 코드를 여덟 가지 언어로 생성합니다. curl, JavaScript, TypeScript SDK, Python, PHP, Go, Ruby, Rust입니다. 시험해 보는 단계에서 첫 연동까지의 길이 복사해 붙여 넣기 한 번으로 줄어들며, 레퍼런스를 처음부터 끝까지 읽지 않아도 됩니다.
KAYZEN의 디자인 가이드, 라이트 테마와 다크 테마
제목에는 Outfit, 본문에는 Plus Jakarta Sans, 색은 네이비, 그리고 주요 행동 유도에는 테라코타. 사이트는 kayzen-lyon.com의 디자인 가이드를 그대로 따라, 이 API가 에이전시의 제품임을 알아볼 수 있게 합니다. 라이트 테마, 다크 테마, 시스템 테마는 표시 옵션에서 선택합니다.
타이포그래피 체계
제목용 서체
Outfit
본문용 서체
Plus Jakarta Sans
kayzen-lyon.com의 두 서체 패밀리로, 이 API가 에이전시의 제품임을 알아볼 수 있게 합니다.
보이지 않는 곳의 기술.
- TypeScript
- Node.js
- Fastify
- Playwright
- Redis
- Tailwind
- Vercel
HTTP 먼저, 브라우저는 필요할 때만
페이지마다 Chromium을 실행하면 시간과 메모리가 듭니다. 그래서 페이지는 먼저 HTTP 요청으로 읽어 분석하고, 결과가 빈약하거나, 페이지가 빈 애플리케이션 셸이거나, 사이트가 차단 페이지를 내보낸 경우에만 브라우저가 이어받습니다. meta.source 필드가 어떤 경로를 거쳤는지 알려 줍니다.
연결마다 적용되는 SSRF 방어
호출자가 제공한 주소를 방문하는 API는 내부 네트워크에 접근하는 수단으로 쓰일 수 있습니다. 사설 주소, 루프백 주소, 클라우드 메타데이터 주소는 거부되며, DNS 조회 결과는 연결 시점에 고정됩니다. 브라우저 안에서는 모든 트래픽이 내부 프록시를 통해 나가고, 이 프록시는 리디렉션을 포함해 연결마다 다시 검증합니다.
호출자가 제공한 코드는 전혀 실행하지 않음
API는 클라이언트가 보낸 스크립트를 일절 실행하지 않습니다. 캡처에 앞서 할 일은 매개변수와 CSS 선택자로 기술합니다. 클릭하기, 스크롤하기, 요소 기다리기입니다. 기능이 하나 빠진 셈이지만 의도한 것입니다. 브라우저에서 임의의 코드를 실행하면 격리와 SSRF 방어에 어긋나기 때문입니다.
읽는 페이지에 쿠키도 인증 정보도 전달하지 않음
호출자가 지정할 수 있는 헤더는 Accept-Language, User-Agent, Referer 세 가지뿐입니다. Cookie와 Authorization은 제외했습니다. 응답이 주소별로 캐시되어 모두에게 제공되기 때문입니다. 한 호출자의 세션으로 받은 페이지가 다음 호출자에게 제공되고 맙니다.
캐시, 중복 제거, 호스트별 서킷 브레이커
결과는 메모리나 Redis에 캐시되며, 동시에 들어온 동일한 요청은 한 번의 처리만 일으킵니다. 서킷 브레이커는 네트워크 실패가 여러 번 연속된 호스트에 더 이상 접속하지 않습니다. 따라서 느린 페이지나 요청이 몰리는 페이지가 사용 가능한 브라우저를 독차지하지 못합니다.
검증 코드에서 뽑아낸 OpenAPI 레퍼런스
OpenAPI 3.1 문서의 매개변수는 라우트의 검증 스키마에서 도출됩니다. 공개된 레퍼런스는 서버가 실제로 받아들이는 내용을 기술합니다. 실패마다 EINVALIDURL부터 ETIMEOUT까지 안정적인 코드와 그에 해당하는 HTTP 상태가 붙어, 클라이언트 코드가 메시지를 분석하지 않고도 처리할 수 있습니다.
AI 에이전트를 위한 MCP 엔드포인트
읽기 전용 도구 여덟 개가 POST /mcp에 노출되어 있습니다. 이 도구들은 REST 라우트와 같은 서비스를 거치므로 같은 검사를 받습니다. 페이지 콘텐츠를 담은 결과는 모두 경고문으로 시작합니다. 이 텍스트는 웹에서 온 것으로, 따라야 할 지시가 아니라 평가해야 할 데이터라는 내용입니다.
함수 하나가 API와 사이트를 모두 제공
Vercel에서는 사이트를 컴파일한 뒤 API 번들에 포함합니다. 함수 하나가 모든 요청에 응답합니다. 요청 하나의 시간 예산은 기본 55초로, 함수의 최대 실행 시간(60초) 바로 아래입니다. 플랫폼에 의해 중단되기보다 API가 직접 읽을 수 있는 오류로 응답하도록 하기 위해서입니다.
사이트가 검색되는 방식.
열여섯 페이지, 각각 프랑스어와 영어로
사이트맵에는 32개 주소가 선언되어 있습니다. 홈, 샌드박스, API 레퍼런스, 가이드 열 편, 서비스 상태, 접근성, 법적 고지이며, 두 언어는 hreflang 태그로 연결됩니다. 개발자는 구체적인 답을 찾습니다. 그래서 각 주제는 한 페이지 안의 섹션이 아니라 자체 페이지를 갖습니다.
어시스턴트를 위한 llms.txt 파일
사이트는 /llms.txt와 /llms-full.txt를 공개합니다. 앞의 파일은 문서를 페이지당 한 줄 요약과 함께 나열하고, 뒤의 파일은 그 전문을 담고 있습니다. 덕분에 이 API에 관한 질문을 받은 코딩 어시스턴트는 매개변수를 추측하는 대신 최신 문서를 읽을 수 있습니다.
구조화 데이터, 그리고 크롤링에서 제외한 API
홈 페이지는 JSON-LD로 발행자, API(WebAPI 유형), 소프트웨어, 자주 묻는 질문을 선언합니다. robots.txt 파일은 /api/를 크롤링에서 제외합니다. API의 응답은 다른 사이트에 관한 데이터이지, Omnillink의 이름으로 색인될 페이지가 아니기 때문입니다.
쿠키도 방문자 분석도 없음
사이트는 쿠키를 전혀 저장하지 않으며 방문자 분석 도구도 불러오지 않습니다. 테마, 언어, 접근성 설정은 브라우저 안에 남습니다. 따라서 문서를 읽기 전에 거쳐야 할 동의 배너가 없습니다.
누구나 사용할 수 있도록.
2025년 6월부터 유럽 접근성법(European Accessibility Act)에 따라 상당수 온라인 서비스에 디지털 접근성이 의무화되었습니다. 저희는 사후 보완이 아니라 설계 단계에서부터 접근성을 다룹니다.
모든 페이지에 있는 옵션 패널
버튼 하나로 표시 설정이 열립니다. 글자 크기, 강화된 대비, Atkinson Hyperlegible 글꼴, 줄 간격, 링크 밑줄, 애니메이션 줄이기입니다. 선택한 내용은 브라우저에 저장되어, 시스템 설정과 관계없이 모든 페이지에 적용됩니다.
확인한 것과 확인하지 못한 것
접근성 페이지에는 2026년 11월 18일에 수행한 확인 항목이 나열되어 있습니다. 두 테마에 대해 계산한 대비, 자동 제어 브라우저에서의 키보드 탐색, 375픽셀 너비에서 가로 스크롤이 없음입니다. 빠진 것도 함께 적었습니다. 스크린 리더로는 시험하지 않았고, 교육받은 사람의 WCAG 또는 RGAA 감사도 받지 않았습니다. 이를 밝혀 두어, 확인되지 않은 적합성이 있는 것처럼 보이지 않게 합니다.
납품한 결과물.
- 홈 — 실시간 데모, 기능, 작동 방식, 자체 호스팅, 자주 묻는 질문
- 샌드박스 — 모든 매개변수, 여덟 가지 언어로 생성되는 코드
- API 레퍼런스 — 라우트, 매개변수, 오류, 할당량, 캐시
- 가이드 — 시작하기, 자체 호스팅, SDK, AI 에이전트, 레시피, 보안, 한계
- 서비스 상태
- 접근성, 법적 고지, 개인정보 보호
프로젝트 진행 과정.
기본 API
메타데이터, 스크린샷, PDF, 추출, 읽기 쉬운 콘텐츠. 주소 검증, 캐시, Vercel에서 함수 하나로 배포.
보안 강화
리디렉션을 포함해 브라우저의 모든 연결을 검증하는 내부 프록시. 알 수 없는 매개변수는 거부하지 않고 무시.
개발자 도구
TypeScript SDK, 명령줄 도구, MCP 서버, React 컴포넌트, GitHub 액션, 연동 예제.
사이트와 공개
샌드박스, 가이드, 검색, 영어 버전, 호스팅되는 MCP 엔드포인트, 변경 기록. 2026년 11월 공개.


