Dostupné

FastAPI skeleton

Kostra (položka 0.8, hotová) dělá tři věci: řekne, že běží, řekne, jaká je to verze, a servíruje vygenerovaný web z jednoho originu. Data o pohledávkách do aplikace přinesly až pozdější routery pod /api/ — popisuje je karta Čtecí API.

Umístění

src/progresus_isir/api/

Endpointy

/health (liveness), /health/ready (readiness), /version (verze, prostředí a commit buildu) a /health/dependencies (databáze a schéma, Redis, úložiště dokumentů, Meilisearch, zpoždění feedu, jistič a rozpočet; diagnostika, ne sonda)

Chyby

application/problem+json podle RFC 9457; dotaz na databázi se schématem starším než build odpoví 503 schema-not-at-head místo holé 500

Veřejné routy

64: 8 v PUBLIC_ROUTES a 56 v DETAIL_PAGES, plus /sitemap.xml a /robots.txt

Stav

hotovo (0.8). Nad kostrou dnes běží /api/explore, /api/review, /api/feedback a /api/news; verzované API /v1 neexistuje

Tabulka rout je kontrakt

Stránky se nemountují jako adresář. Každá routa je vyjmenovaná, takže tabulka je kontrakt a stránka, která leží na disku, ale v tabulce není, není tiše dostupná.

Že se tabulka shoduje se seznamem stránek v buildu, ověřuje e2e sada. Stránka přidaná do buildu bez routy shodí bránu, místo aby později vracela 404.

Chyba má jeden tvar

Odpověď na chybu je vždycky problem+json s typem, titulkem, stavem a detailem. Klient nemusí rozlišovat, jestli chybu vyrobil framework, nebo aplikace.

Do budoucna to má cenu hlavně u čtecího API: chyba „nedostatečná spolehlivost, hodnota je ve frontě kontroly“ musí být strojově odlišitelná od „nenalezeno“.

Jeden origin

Web se servíruje z téže aplikace jako API, takže stránky aplikace pod /app volají /api/… bez CORS. Statické stránky jsou přitom pořád commitnutý generovaný výstup, ne šablony renderované za běhu.

Kde to v repozitáři žije

• src/progresus_isir/api/ — aplikace, obálka chyb a routery
• src/progresus_isir/api/routers/health.py — liveness, readiness, verze buildu a diagnostika závislostí
• src/progresus_isir/api/routers/web.py — explicitní tabulka veřejných rout
• docs/API.md — co z API existuje a co je jen navržené (/v1)

Souvisí

Zpět na sekci Roadmapa