Jak řešit konflikty ve verzování API s GraphQL a SQL?

Verzování API je celkem oříšek, obzvlášť když jedeš na GraphQL. Základní pravidlo je snažit se dělat zpětně kompatibilní změny. Když měníš strukturu, třeba přidáváš nové pole místo toho, abys něco mazal. Klient, co už funguje, by měl mít pořád šanci se dostat k těm starším datům. Pokud už musíš něco vyhodit, je lepší to udělat až po nějakém přechodném období, kdy to budeš deprekovat a dáš lidem vědět, že to zmizí. Co se týče verzování, tak jsou dva přístupy – buď mít víc verzí API (např. /v1/, /v2/), nebo se snažit evolvovat to stávající bez verzí. Osobně preferuju evoluci, ale je to na zvážení. Dokumentace je pak zásadní – jasně popiš změny v changelogu a dej tam příklady dotazů. U SQL databáze pak musíš dávat pozor na migrace a dodržovat pravidla pro úpravy tabulek, aby se to nedotklo front-endu. Takže v krátkosti: zpětná kompatibilita, jasná dokumentace a přechodné období jsou klíčové faktory.

Takže ohledně verzování API s GraphQL a SQL, to je fakt oříšek. Když máš GraphQL, tak si můžeš šáhnout na cokoliv a to je super, ale přesně jak říkáš, ty změny pak můžou rozbít starší klienty. Osobně doporučuju používat versioning na úrovni endpointů, třeba /api/v1/ a pak /api/v2/, i když někteří říkají, že bys měl spíš evolvovat to stávající API a ne dělat nové verze. Záleží na tom, jak velké změny děláš. Pokud měníš strukturu dat, tak je dobrý mít nějaký systém na přesměrování nebo fallback, aby ti to nebombardovalo staré aplikace.

Co se týče SQL, tam se snažím dodržovat migrace a verzování databáze. Každá změna v DB by měla mít migraci, což ti pomůže udržet přehled o tom, jak se struktura mění. Měj na paměti, že někdy je lepší udělat "non-breaking changes", jako třeba přidat nový field místo toho, abys přepsal existující. A dokumentace? Určitě mít nějakou formu dokumentace pro změny je klíčový, ale nemusíš to přehánět s detaily. Měl bys mít aspoň poznámky o tom, co se kdy změnilo a proč.

Každý to dělá trochu jinak, ale u mě se osvědčilo mít pravidelný schůzky s týmem a projít si plánované změny a co to znamená pro klienty. Když se dělají větší refaktoringy, tak je fajn mít beta verzi pro testování před tím, než to vypustíš do světa. Takže tak nějak v kostce - versioning endpointů, migrace DB, non-breaking changes a solidní dokumentace. Snad to pomůže!

Takže, když jde o verzování API s GraphQL a SQL, tak to může být docela oříšek. U GraphQL máš tu výhodu, že si klienti můžou dotazovat, co potřebují, ale jakmile změníš strukturu, můžeš narazit na problémy. Nejlepší je asi se snažit dodržet zpětnou kompatibilitu. Třeba přidávat nové pole místo toho, abys stávající měnil nebo mazal. To pomůže udržet stávající klienty v chodu.

Co se týká SQL, tam je to často o migracích. Změny v databázi by měly být dobře naplánované, a pokud je to možné, tak používat přidání nových sloupců a tabulek místo zásahů do existujících. Pokud už něco měníš, tak je dobré mít nějaký testovací prostředí, kde to vyzkoušíš.

Pokud jde o verze API, já bych doporučil mít spíš jednu verzi a vyvíjet ji evolučně. Různé verze mohou zbytečně komplikovat údržbu. A ohledně dokumentace – měl bys mít jasný přehled změn, ideálně s příklady dotazů a odpovědí. V tomhle ohledu se hodí nástroje jako Swagger nebo něco podobného pro generaci dokumentace.

V praxi jsme si osvědčili mít changelog, kde jasně popíšeme, co se změnilo. To pak usnadní život nejen nám, ale i klientům, kteří to používají. Obecně se snažím komunikovat se všemi uživateli API, aby věděli o změnách dopředu.