Nejlepší vizitka vývojáře není životopis. Je to něco, co běží a funguje — něco, co si člověk otevře, použije a řekne si „aha, tohle je šikovný". Proto jsem si na web přidal sekci Aplikace: pár malých veřejných nástrojů a otevřených API. Zadarmo, bez registrace, bez klíčů. Vznikly zčásti proto, že se hodí mně samotnému, a zčásti proto, že mě jejich stavba prostě baví. A upřímně — každý z nich mě něco naučil.

Co tam zatím najdete

  • České jmeniny — kdo má dnes (nebo kterýkoli den) svátek, a reverzně: kdy má svátek zadané jméno.
  • QR Platba — z čísla účtu a částky složí českou QR platbu (SPAYD) a spočítá IBAN.
  • Státní svátky — dny pracovního klidu včetně pohyblivých Velikonoc a kolik je mezi dvěma daty pracovních dní.
  • Validátory — sedí kontrolní číslice IČO, rodného čísla, DIČ nebo IBAN?

Všechno vrací čistý JSON, funguje přímo z prohlížeče a nepotřebuje žádný klíč. Za tou zdánlivou jednoduchostí se ale schovává pár rozhodnutí, která stojí za rozepsání — protože přesně na nich se pozná rozdíl mezi hračkou na víkend a něčím, co vydrží běžet.

1. Rate-limit, který za Cloudflare vůbec funguje

Veřejné API bez omezení je pozvánka k problémům. Napsat limit na počet požadavků z jedné IP je přitom skoro triviální — dokud si neuvědomíte, že web běží za Cloudflare.

Když totiž vezmete IP adresu tak, jak vám ji předloží server, dostanete adresu Cloudflare, ne návštěvníka. Provoz úplně všech uživatelů se slije do hrstky adres — a limit pak buď odstřihne všechny naráz, nebo nikoho. Skutečná IP návštěvníka přichází v hlavičce CF-Connecting-IP; teprve podle ní má smysl počítat. Na tu jsem limit pověsil (120 požadavků za minutu na IP), a při jeho překročení vrací API čistou chybu 429 s hlavičkou Retry-After.

Zároveň je fér přiznat, co takový limit umí a co ne. Zastaví zběsilé bušení z jednoho stroje. Distribuovaný útok z tisíců adres nezastaví — od toho je právě Cloudflare vepředu. Ochrana na úrovni aplikace a ochrana na okraji sítě nejsou totéž a jedno druhé nenahradí.

Za reverzní proxy je první otázka vždycky: čí IP to vlastně vidím?

2. Aby to bylo API, ne náhodou obarvená stránka

Tři hlavičky dělají z obyčejného endpointu použitelné API:

  • Access-Control-Allow-Origin: * — aby na něj směl zavolat i JavaScript v cizím prohlížeči. Bez toho je „veřejné API" použitelné jen ze serveru.
  • X-Robots-Tag: noindex — syrový JSON nemá co dělat ve výsledcích Googlu. Indexovat se má dokumentace, ne odpověď { … }.
  • Cache-Control na míru každému endpointu — „kdo má dnes svátek" se o půlnoci mění, konkrétní datum je neměnné napořád. Každý endpoint tak má vlastní dobu platnosti a zbytečně nezatěžuje origin.

Detaily, kterých si nikdo nevšimne, dokud nechybí. Přesně proto stojí za to je udělat pořádně.

3. Matematika, kterou si nesmíte dovolit splést

U QR platby jde o reálné peníze. Když z čísla účtu skládáte IBAN, kontrolní číslice (mod 97) musí sednout na jedničku — jinak platbu pošlete do neznáma. První, co jsem udělal, bylo ověření proti známému účtu; teprve když všechno sedělo, šel jsem dál.

Podobné je to se svátky. Pevné datum je snadné, ale Velký pátek a Velikonoční pondělí se každý rok posouvají. Datum Velikonoc se počítá algoritmem starým pár set let a z něj se dopočítají oba svátky. Ověřil jsem to napříč lety proti referenci — protože „skoro správně" je u kalendáře k ničemu.

Společný jmenovatel je determinismus: stejný vstup, stejný výstup. Dá se to cachovat, dá se to testovat a nic se „nerozbije jen občas".

Soukromí není detail: rodné číslo nikam neposílám

Validátory ukazují ještě jednu zásadu. Rodné číslo je citlivý údaj. Kdybych ho ověřoval na serveru, putovalo by v adrese požadavku a skončilo — byť nechtěně — v serverových logách. Proto celá validace (IČO, rodné číslo, DIČ i IBAN) běží přímo ve vašem prohlížeči. Číslo váš počítač neopustí.

Serverové API existuje taky, pro vývojáře. Ale u citlivých dat je klientská validace principiálně správnější volba. Ne všechno musí na server.

Vezměte si to

Nástroje jsou na /aplikace, zdarma a bez klíčů. Klidně je zapojte do svého projektu — od toho tam jsou. A pokud z celého článku plyne něco obecnějšího, pak tohle: hotová, běžící věc řekne o řemesle víc než sebehezčí výčet dovedností.

Když potřebujete postavit něco vlastního — bezpečně a tak, aby to vydrželo — ozvěte se.