A JSON ma annyira megszokott, hogy könnyű természetes adottságnak tekinteni. Mobilalkalmazások rendelést küldenek benne, böngészők profilokat töltenek le, belső szolgáltatások eseményeket cserélnek. Nem azért győzött, mert minden más formátumnál kisebb vagy pontosabb, hanem mert kevés, könnyen érthető építőelemmel adott közös nyelvet eltérő programozási környezeteknek. Közel állt a JavaScript objektumaihoz, egyszerűen lehetett parsolni, és külön eszköz nélkül is olvasható maradt.

A kis típusrendszer csökkentette a belépési küszöböt

A JSON objektumot, tömböt, stringet, számot, logikai értéket és nullt ismer. Nincsenek osztályok, kommentek, dátumok vagy natív bináris mezők. Emiatt szinte minden nyelvben gyorsan megjelent egy stabil parser és serializer.

Az egyszerűség ára, hogy a jelentést a szerződésnek kell hozzáadnia. A dátum csak string, a pénz lehet szám vagy string, a bájtokhoz Base64 vagy külön szállítás szükséges.

A böngésző és a JavaScript felgyorsította az elterjedést

A frontend fejlesztők számára a struktúra ismerős volt, és a böngésző könnyen alakította objektummá. Az XML-hez kapcsolódó nehezebb toolchain sok egyszerű webes feladathoz feleslegesnek tűnt.

A JSON azonban nem futtatható JavaScript. Biztonságos alkalmazás parsert használ, nem eval-t. A szabvány szigorúbb az idézőjelek, kulcsok és számok kezelésében.

Az olvasható szöveg gyorsítja a hibakeresést

Egy választ meg lehet nézni DevToolsban, curl kimenetben vagy naplóban. A mezőnevek generált kliens nélkül is hozzávetőleges jelentést adnak. Ez különösen értékes az integráció első napjaiban és incidens közben.

Az olvashatóság többletet jelent. A kulcsok ismétlődnek, a számok és bájtok szöveges formát kapnak. HTTP tömörítés sokat segít, de nagy throughput esetén bináris protokoll lehet gazdaságosabb.

Az objektum és a tömb jól írja le a gyakori erőforrásokat

Egy felhasználói profil, rendelés vagy konfiguráció természetesen ábrázolható egymásba ágyazott objektumokkal. Egy lista tömbként adható vissza, a metaadat pedig külön mezőkbe kerülhet.

A rugalmasság könnyen következetlenséggé válik. Az egyik endpoint közvetlen tömböt, a másik data burkot, a harmadik teljesen más pagination struktúrát ad. Szervezeti konvenciókra a szintaxison túl is szükség van.

A HTTP és a JSON külön réteget old meg

A JSON a body szerkezetét írja le. A HTTP metódust, státuszt, cache-t, autentikációt és tartalomtípust kezel. Ha minden hiba 200 státuszba és egy JSON flagbe kerül, a proxy, monitoring és általános kliens elveszíti a szabványos információt.

A Content-Type legyen pontos, a kliens pedig ellenőrizze. Egy proxy által visszaadott HTML hibaoldal nem „rossz JSON”, hanem váratlan válaszréteg.

A számok nem minden nyelvben azonosak

A JSON nem különböztet integer és decimal típust. A JavaScript nagy egész számoknál elveszítheti a pontosságot. Adatbázis-ID vagy pénzösszeg ezért biztonságosabb lehet stringként vagy pontosan dokumentált tartományban.

A NaN és Infinity nem szabványos JSON érték. A serializernek el kell utasítania vagy szerződés szerint más alakra kell képeznie, nem csendben nem interoperábilis választ készítenie.

A null, a hiányzó mező és az üres érték különbözik

Egy PATCH kérésben a hiányzó mező jelentheti azt, hogy „ne változtasd”, a null azt, hogy „töröld”, az üres string pedig legitim érték lehet. Ha a kliens vagy szerver összemossa őket, adatvesztés következhet be.

A required és nullable szabályokat a sémának és a doménleírásnak is rögzítenie kell. A típusos SDK csak akkor segít, ha ugyanazt a jelentést valósítja meg.

Az objektum kulcssorrendje nem szerződés

A fogyasztó ne építsen arra, milyen sorrendben jelennek meg a properties. Serializer, adatbázis vagy middleware átrendezheti őket. Ha a sorrend jelentést hordoz, tömböt kell használni.

Aláírásnál ez különösen fontos. Két szemantikailag azonos objektum eltérő whitespace-szal más bájtokat ad. Canonical JSON vagy az eredeti serializáció megőrzése szükséges.

A cache stabil jelentést és HTTP szabályokat igényel

Az ETag egy erőforrásverziót képviselhet, a Cache-Control pedig meghatározza a frissességet és a megoszthatóságot. Személyes válasz nem kerülhet véletlenül közös cache-be.

Ha a szerver minden kérésnél véletlenszerű metaadatot vagy más kulcssorrendet generál, a byte-level cache validáció kevésbé hatékony. A JSON alakja és a cache policy együtt tervezendő.

A tömörítés nem javítja a rossz adatmodellt

A gzip és Brotli jól tömöríti az ismétlődő mezőneveket, de a kliensnek a kicsomagolt, nagy objektumot továbbra is parsolnia kell. CPU- és memóriaigény marad.

Ha egy mobilkliens rendszeresen ezernyi szükségtelen mezőt kap, jobb szűkebb endpointot, paginationt vagy más protokollt kialakítani, mint kizárólag erősebb tömörítésre támaszkodni.

A séma teszi hosszú távon használhatóvá

OpenAPI, JSON Schema és contract tests rögzítheti a neveket, típusokat, enumokat és kötelező mezőket. A dokumentáció példákkal és üzleti jelentéssel egészíti ki őket.

A JSON azért lett a webes API-k nyelve, mert hordozható, olvasható és elég kifejező. A tartós minőséget azonban a stabil szerződés, a helyes HTTP használat és a séma tudatos evolúciója biztosítja.

Az olvashatóság nem jelent automatikus biztonságot

A parser által létrehozott objektum továbbra is megbízhatatlan adat. A szervernek méret-, mélység- és elemszámkorlátot kell alkalmaznia, mielőtt egy támadó óriási vagy szélsőségesen egymásba ágyazott dokumentummal erőforrást fogyaszt. A mezőnevek sem kerülhetnek ellenőrizetlenül SQL, fájlútvonal vagy template részeként felhasználásra.

A mass assignment külön kockázat: ha a request minden propertyje automatikusan modellmezővé válik, a kliens olyan flaget is beállíthat, amelyet a felület nem mutatott. A szerver explicit allowlist alapján képezi át a szerződés mezőit doménparanccsá.

A részleges válasz és a túl sok adat közötti egyensúly

Egyetlen hatalmas „mindent visszaadó” endpoint egyszerűnek tűnik, de sávszélességet, parse időt és privacy kockázatot növel. Külön erőforrások, pagination vagy dokumentált field selection csökkentheti a payloadot.

A dinamikus mezőválasztás viszont cache-variánsokat és authorization kérdéseket hoz létre. Nem minden mező kérhető minden felhasználónak. A teljesítményoptimalizálásnak ugyanazt a hozzáférési politikát kell követnie, mint az alapválasznak.