Prvá verzia JSON API sa navrhuje ľahko, pretože server aj klient vznikajú súčasne. Skutočný test prichádza po mesiacoch, keď existujú mobilné aplikácie bez okamžitého upgradu, partnerské integrácie, uložené payloady a interné joby. Zmena názvu poľa alebo významu null už nie je lokálny refactor. Je to úprava verejnej zmluvy. Odolné rozhranie preto počíta s evolúciou od prvého dňa a uprednostňuje čitateľné, rozšíriteľné tvary pred krátkodobou úsporou znakov.

Pridávanie je bezpečnejšie než prepisovanie významu

Nové voliteľné pole obyčajne starého klienta nepoškodí, ak neznáme vlastnosti ignoruje. Zmena typu z čísla na objekt alebo premenovanie kľúča už kompatibilná nie je. Spotrebiteľ môže zlyhať pri parsovaní alebo, horšie, nesprávne interpretovať novú hodnotu.

Pri väčšej zmene je vhodné pridať nové pole, určitý čas emitovať oba tvary, merať používanie a až potom starý odstrániť v jasne komunikovanej verzii.

Klient má byť tolerantný iba správnym smerom

Spotrebiteľ môže ignorovať neznáme response fields, aby server mohol odpoveď rozšíriť. Nemal by však tolerovať nesprávny typ, chýbajúce povinné pole alebo neznámu hodnotu, ak od nej závisí bezpečné rozhodnutie.

Server pri requeste často potrebuje prísnejšie pravidlá. Preklep v názve poľa sa nemá potichu ignorovať a vytvoriť objekt s defaultom. Chyba má ukázať konkrétnu cestu a očakávaný typ.

Null a neprítomnosť potrebujú stabilnú semantiku

Pri update requeste môže chýbajúce pole znamenať „ponechaj hodnotu“ a null „vymaž ju“. Ak server oba stavy zlúči, čiastočná aktualizácia sa stane nebezpečnou. Rovnaké pravidlo musí platiť v SDK, validátore aj databázovej vrstve.

Prázdne pole, prázdny objekt a prázdny string sú ďalšie legitímne stavy. Doménový model má určiť, ktoré z nich sú povolené, namiesto všeobecného odstraňovania „falsy“ hodnôt.

Stabilné identifikátory nepatria do názvov

Používateľské meno, slug alebo lokalizovaný názov sa môže zmeniť. Ak slúži ako jediný cudzí kľúč, každá zmena rozbije odkazy. API má poskytovať stabilný identifikátor a prezentačné polia držať oddelene.

Veľké integer ID môže byť v JavaScripte nepresné. UUID alebo číselný identifikátor serializovaný ako string sa prenáša bezpečnejšie, ak zmluva jasne určuje formát.

Enum nie je navždy uzavretý zoznam

Server môže časom pridať nový stav objednávky. Klient s exhaustive switch bez fallbacku môže spadnúť alebo zobraziť prázdnu obrazovku. Response enumy sa majú navrhovať ako rozšíriteľné tam, kde produkt očakáva vývoj.

Naopak request enum musí server validovať prísne. Klient nesmie poslať neznámu operáciu a očakávať, že sa nejako vykoná. Smer dát ovplyvňuje politiku kompatibility.

Obálka odpovede poskytuje priestor na rast

Pri kolekciách je praktické oddeliť data od pagination, links a metadata. API môže neskôr pridať cursor či warning bez zmeny typu hlavnej kolekcie. Jednoduchý endpoint nemusí mať zbytočne hlbokú štruktúru, no spoločná konvencia znižuje počet výnimiek.

Chybová obálka má stabilný strojový code, ľudskú správu, request ID a voliteľné field errors. Klient nemá parsovať lokalizovaný text, aby zistil ďalší krok.

Dátum a peniaze potrebujú presný formát

Časový okamih sa má prenášať v jednoznačnom ISO 8601 tvare s offsetom alebo ako presne pomenovaná epoch jednotka. Lokálny kalendárny dátum sa nesmie automaticky meniť na UTC polnoc. Suma potrebuje menu a reprezentáciu bez nečakaného floating-point zaokrúhlenia.

Tieto rozhodnutia sa zdajú malé, no po rozšírení API do ďalších jazykov a časových zón sa menia veľmi ťažko.

Pagination musí zostať stabilná pri zmene dát

Offset pagination je jednoduchá, ale pri súbežnom pridávaní záznamov môže preskakovať alebo opakovať položky. Cursor založený na stabilnom poradí je vhodnejší pre veľké či často meniace sa kolekcie.

Kontrakt musí definovať sort order a tie-breaker. Bez nich ani cursor nedokáže zaručiť predvídateľné pokračovanie.

Verzia nie je náhrada za kompatibilitu

Číslo v URL alebo hlavičke pomáha pri vedome nekompatibilnej zmene, ale každá nová verzia znásobuje dokumentáciu, testy a podporu. Väčšinu vývoja je lacnejšie riešiť kompatibilným rozšírením existujúcej schémy.

Keď je nová verzia potrebná, musí mať migračný návod, telemetry adoption a dátum ukončenia starej. „V2 existuje“ neznamená, že spotrebitelia prešli.

Kontraktné testy chránia obe strany

Schema validácia zachytí typy a required fields. Consumer-driven testy ukážu, ktoré časti odpovede partner skutočne používa. Produkčné metriky odhalia staré verzie a deprecated fields pred odstránením.

Zápisové operácie potrebujú idempotentnú identitu

Klient po timeoute nevie, či server objednávku vytvoril. Ak zopakuje POST bez ochrany, môže vzniknúť duplikát. Idempotency key viazaný na používateľa, endpoint a stabilný request umožní serveru vrátiť pôvodný výsledok. Rovnaký kľúč s iným obsahom musí skončiť konfliktom, nie prepísaním histórie.

JSON telo je vhodné pred porovnaním kanonizovať podľa doménových polí alebo uložiť jeho bezpečný digest. Náhodné poradie properties nesmie rozhodnúť, či ide o rovnakú operáciu.

Deprecation musí byť pozorovateľná

Označenie poľa v dokumentácii nestačí. Server má vedieť, ktorí klienti a partneri starú vlastnosť stále posielajú alebo čítajú. Verzia SDK, client ID a samostatná metrika umožnia kontaktovať vlastníka a určiť realistický termín odstránenia.

Warning hlavička alebo response metadata môže vývojára upozorniť počas testovania, no nesmie rozbiť automatické spracovanie. Po skončení migrácie treba kompatibilnú vetvu skutočne odstrániť, inak každá ďalšia zmena násobí kombinácie správania.

Odolné JSON API nie je nemenné. Mení sa riadeným spôsobom: pridáva nové možnosti, zachováva starý význam počas migrácie a odstraňuje ho až na základe dôkazov. Najdôležitejšou vlastnosťou nie je elegantná prvá schéma, ale predvídateľná cesta medzi verziami.