Інженерні нотатки.
Про точність ефемерид, архітектуру обчислень, MCP-протокол і всі дрібниці, які не вміщуються у docs.
Документація, зроблена для AI-агентів, а не тільки для людей
Класична документація зроблена під людські очі: гарний HTML, підсвітка коду, навігація. Але половина трафіку до docs тепер - агенти й асистенти, яким потрібен plain-text, а не рендер. Розбираємо, що ми додали: .md-двійник кожної сторінки, llms.txt, машиночитані специфікації, dropdown «відкрити в ChatGPT / Claude» і inline try-it.
Read →Нумерологія в API: 5 систем розрахунку за одним маршрутом
Більшість API або взагалі не мають нумерології, або дають одну піфагорійську систему. У нас 5 повних систем (піфагорійська, халдейська, дві кабалістичні, ведична) по 10 розрахунків кожна, за одним параметризованим маршрутом. Плюс Матриця Долі на 22 аркани.
Read →Типізований вивід MCP: чому 600+ інструментів мають outputSchema
Більшість MCP-серверів віддають агенту нетипізований JSON - модель мусить вгадувати форму відповіді. Ми публікуємо строгий outputSchema для 600+ інструментів. Розбираємо, як це працює, який баг це відкрило у strict-mode клієнтів і як ми його полагодили через відкриті схеми.
Read →Карта каталогу: як влаштовані 700+ ендпоінтів AstroWay
API виріс до понад 700 ендпоінтів у 57 групах - від натальної карти до BaZi, геомантії та рендеру SVG-карт. Розбираємо, як каталог поділений на домени, за яким єдиним патерном ходять усі виклики і як швидко знайти потрібний ендпоінт.
Read →Як ми тримаємо точність під контролем: CI проти swetest і NASA
Точність в астро-API легко деградує від одного рефакторингу ефемерид. Розбираємо захист: одне ядро Swiss Ephemeris на браузер і сервер, сотні заморожених снапшотів на еталонних картах і триангуляція кожного PR проти swetest CGI, Kerykeion, Prokerala та каталогу затемнень NASA.
Read →Три офіційні SDK: TypeScript, Python, PHP замість сирого curl
Сирий HTTP працює, але типізований клієнт економить години: автодоповнення шляхів, типи запиту й відповіді, вбудований retry на 408/409/429/5xx і Stainless-style ієрархія помилок. Розбираємо три офіційні SDK - @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist) - і чим вони згенеровані з одного OpenAPI-контракту.
Read →X-Cache header: видимий cache-status для оптимізації клієнтських інтеграцій
Кожна response API тепер несе X-Cache: MISS | HIT | BYPASS - клієнт відразу бачить чи запит обчислений з нуля, чи витягнутий з кешу. Це відкриває cache hit % колонку в /dashboard/usage та дозволяє оптимізувати інтеграцію без guesswork.
Read →Eclipse path, cosmogram і Vedic-карти: pure-SVG візуалізатори без headless-Chrome
Шість ендпоінтів сімейства /v1/render/* для специфічних візуалізацій - три Vedic-картки (North/South/East Indian), Hamburg-School 90° cosmogram, equirectangular eclipse-path та stereographic star-map. Усі рендери - чистий SVG-стрінг, без браузерного worker-а.
Read →