Jak spravovat verze JSON odpovědí v GraphQL API?

Když řešíš verzování JSON odpovědí v GraphQL, tak je fajn mít na paměti pár věcí. Osobně preferuju spíš udržovat zpětnou kompatibilitu, než mít víc verzí endpointu. Když se něco mění, snažím se adaptovat stávající dotazy a přidávat nové pole nebo argumenty místo toho, abych vytvářel úplně nový endpoint. Je dobrý nápad do odpovědi přidat pole s verzí, aspoň víš, s čím pracuješ a jak to ovlivňuje front-end. Tím pádem můžeš lépe řídit, co se kde používá a kdy je potřeba něco změnit. Z praxe vím, že když uděláš breaking change, tak to pak dost komplikuje život všem, kdo se na to napojují. Vždycky je lepší mít přehled a dávat prostor pro evoluci API bez velkých skoků. Takže klidně přidej novou strukturu a měj starou jako deprecated, ale snaž se to udržovat pokud možno čisté a jednoduché. Hlavně komunikuj s týmem a front-end vývojáři, aby věděli o všech změnách. To hodně pomáhá.

No, verzování v GraphQL je dost zajímavý téma. Sice je to trochu jiný než u REST, ale stejně si s tím lidi lámou hlavu. Osobně se snažím držet zpětnou kompatibilitu co nejdéle, protože když začneš měnit strukturu, tak to může na frontendu nadělat škody. Místo víc verzí endpointu bych radši přidal nové pole nebo argumenty, co bys mohl používat podle potřeby.

Taky jsem viděl, že někdo dal verzi přímo do JSON odpovědi a fungovalo to. Tím pádem klient vždy ví, co dostává a může se na to adaptovat. Sice to přidává nějakou složitost, ale pokud máš dobře vyvinutý schema, tak to snášíš snadno. Frontend pak může reagovat na změny, aniž by se musel dělat velký zásah do kódu. Takže jo, asi bych řekl, že klíčem je mít jasně definovanou strukturu a snažit se minimalizovat zásahy do toho, co už funguje.

Když řeším verze JSON odpovědí v GraphQL, tak se snažím udržovat zpětnou kompatibilitu. Většinou to dělám tak, že při změně struktury dat se snažím přidávat nové pole místo toho, abych měnil nebo odstraňoval existující. Tím pádem staré dotazy furt fungují a klienti nemusí nic měnit. Občas ale prostě musíš udělat breaking change, a v tom případě bych rozdal verze endpointů. Třeba /v1/ a /v2/ pro různé struktury. Je to tak přehlednější, zvlášť když se člověk dostane do situace, kdy už nemůžeš udržet staré dotazy funkční bez toho, aby to bylo neúnosně složité.

Někdo doporučuje přidat do JSON odpovědi pole s verzí API, ale já osobně to moc nepoužívám. Spíš si říkám, že když už je endpoint verzovaný, tak je jasný, jakou verzi používáš. Na front-endu to pak obvykle hodně závisí na tom, jak máš napsaný kód – pokud používáš nějakou stabilní knihovnu jako Apollo, tak to většinou zvládá dobře.

Když už mluvím o front-endu, je dobrý mít nějaký způsob, jak reagovat na změny – třeba pomocí feature flagů nebo gradual rolloutů. Takže i když uděláš změny na API, můžeš je nasadit postupně a dávat pozor na to, jak reagují uživatelé. Myslím si, že důležité je mít dobré testy a dokumentaci k API – pomůže to minimalizovat problémy při změnách.