Slovník pojmů

JSON

JSON je běžný zápis dat pro HTTP API, konfigurační soubory a integrační zprávy. Formát říká, jak text zapsat; neříká, která pole jsou povinná, kdo smí zprávu poslat ani co mají hodnoty znamenat.

Stručná definice

Přenos dat v textové podobě, ne hotový kontrakt aplikace.

JSON dokument obsahuje jednu hodnotu: objekt, pole, řetězec, číslo, boolean nebo null. Objekt zapisuje dvojice jméno–hodnota v uvozovkách, pole drží uspořádané hodnoty. Díky malému počtu konstrukcí je formát snadno zpracovatelný v prohlížeči, PHP, databázových nástrojích i externích API.

Platný JSON však nemusí být platná zpráva aplikace. Objekt s polem price může být syntakticky správný, ale stále může mít nečekaný typ, chybět mu měna nebo porušovat business pravidlo. API proto vedle parsování JSONu validuje schéma, oprávnění, kontext organizace a návaznost na aktuální data.

K čemu se používá

Předání dat mezi klientem, API, frontou a konfigurací

JSON se hodí pro strukturovanou zprávu, pokud všechny strany znají její kontrakt a limity.

HTTP request a response REST API, například objednávka, produkt nebo validační chyba
payload webhooku a zpráva předávaná přes integrační frontu
konfigurace frontendového buildu nebo nástrojů, kde není potřeba složitější jazyk
uložený read model či dokument, pokud je jasně určené schéma, verze a vyhledávací potřeby
logovaná strukturovaná událost, kterou lze později filtrovat a analyzovat

Praktický příklad

Webhook objednávky s oddělením formátu a pravidel

Dopravce odešle JSON s identifikátorem objednávky a stavem zásilky. Příjemce nejprve ověří HMAC podpis HTTP požadavku, dekóduje JSON a validuje, že event je podporovaný. Potom dohledá objednávku v aktuálním tenantovi a idempotentně uloží novou informaci. Validní JSON s cizím orderId tedy sám o sobě neznamená povolenou změnu.

Položka amount je zde celočíselná hodnota v haléřích; měna je uvedená samostatně. Integrace se tak nespoléhá na rozdílné zaokrouhlení desetinného čísla mezi odesílatelem a příjemcem.

{
  "event": "shipment.delivered",
  "orderId": "ord_8f2c",
  "amount": 129900,
  "currency": "CZK"
}

Jak funguje

Od HTTP těla k ověřenému aplikačnímu vstupu

Parsování je jen první krok. Aplikace musí oddělit syntaktickou chybu, neplatná data a nepovolenou operaci.

Přijetí zprávy Server ověří HTTP metodu, Content-Type, velikost těla a případně podpis webhooku dříve, než data předá aplikaci.
Dekódování JSON parser převede text na struktury konkrétního jazyka. Neplatné uvozovky, čárky či encoding způsobí syntaktickou chybu.
Validace kontraktu Aplikace kontroluje povinná pole, datové typy, rozsahy a neznámé hodnoty. Pro veřejné API se tento kontrakt dokumentuje a verzovaně udržuje.
Autorizace a business pravidla I dobře validovaný JSON nesmí změnit objednávku bez správného uživatele, tenanta a aktuálního stavu v databázi.
Odpověď a observabilita Server vrátí strukturovanou odpověď či bezpečnou chybu. Log ukládá sledovatelný identifikátor, ne celý citlivý payload bez omezení.

Základní vlastnosti

Datové typy a přesnost je potřeba znát na obou stranách.

JSON není objektový model konkrétního jazyka. Převod mezi formátem a typy aplikace vyžaduje vědomá pravidla.

Objekt a pole

Objekt má pojmenované členy, pole zachovává pořadí hodnot. Jména objektových členů jsou řetězce v dvojitých uvozovkách; komentáře a koncové čárky standardní JSON neumožňuje.

Řetězec a UTF-8

JSON text se v otevřeném ekosystému přenáší v UTF-8. Znakové escapování řeší zápis uvozovek či řídicích znaků, ale nepřebírá odpovědnost za bezpečné HTML zobrazení.

Čísla a peníze

JSON nemá oddělený desetinný typ. Při přenosu cen je nutné dohodnout měnu a reprezentaci, například integer minor units nebo řetězec, aby se nepřenesla chyba plovoucí čárky.

null, chybějící a výchozí hodnota

Chybějící pole, null a prázdný řetězec mohou mít odlišný význam. Kontrakt musí říct, kdy je pole nepovinné, kdy lze hodnotu vymazat a kdy je vstup neplatný.

Content-Type

HTTP zpráva s JSONem běžně používá application/json. Hlavička pomáhá klientovi i serveru zvolit parser, ale sama neověřuje správnost dat.

Vztah k ostatním pojmům

JSON je formát zprávy, API je kontrakt a OpenAPI je jeho popis.

Tato hranice brání častému omylu, že JSON endpoint je automaticky kvalitně navržené API.

API: API určuje, co klient může volat, jak se autentizuje a jaké chování očekává. JSON je jen jeden možný formát těla zprávy.
OpenAPI: OpenAPI popisuje cesty, parametry, zabezpečení a schémata HTTP API. Jeho dokument lze zapisovat jako JSON nebo YAML, ale JSON sám specifikaci nenahradí.
Webhook a HMAC: Webhook často nese JSON payload. Příjemce ještě ověřuje podpis, chrání se proti replay a validuje konkrétní událost.
Symfony a Laravel: Frameworky pomáhají parsovat request a vracet odpověď, ale formát dat musí stále projít validací a aplikačními pravidly.

Výhody a omezení

Jednoduchý formát, který potřebuje přesně popsanou interpretaci.

Přínosy

široká podpora napříč prohlížeči, PHP a integračními službami
čitelná struktura pro debugging i dokumentaci
přirozená podpora objektů a polí pro běžné HTTP zprávy
snadné předání do logu či fronty při rozumném omezení velikosti

Rizika a chyby

platná syntaxe neznamená validní business vstup
čísla bez domluveného významu mohou poškodit ceny, identifikátory nebo přesnost
velký či hluboce vnořený payload může vyčerpat paměť a zkomplikovat logování
neescapovaný JSON vložený do HTML nebo JavaScriptového kontextu může otevřít bezpečnostní problém
neznámá pole a změny významu bez verze rozbijí integrační klienty

Hranice použití

Použít pro data, ne jako náhradu za typy, validaci a autorizaci.

JSON je praktický pro API a integrační zprávy, pokud je zároveň určena maximální velikost, verze kontraktu, povinná a volitelná pole i způsob vracení chyby. Pro streaming velkých importů, binární soubory nebo extrémně objemná data může být vhodnější jiný formát či dávkové zpracování místo jednoho velkého JSON requestu.

Při přijímání nedůvěryhodného JSONu je nutné omezit request body, dekódovat s chybovou kontrolou a validovat strukturu dříve, než se hodnoty dostanou do databáze nebo doménové logiky. Zabezpečení neřeší samotný zápis JSONu; vyžaduje také HTTPS, autentizaci, autorizaci, ochranu před duplicitním doručením a bezpečné logování.

Na co myslet

Kontrakt verzovat a chyby vracet strojově čitelně.

Datová výměna funguje dlouhodobě jen tehdy, když obě strany znají stejný význam struktury.

uvádět application/json a odmítnout nečitelný nebo nepřiměřeně velký request body
validovat povinná pole, datové typy, rozsahy, enum hodnoty i závislosti mezi poli
u peněz, času a identifikátorů jasně zvolit reprezentaci a časové pásmo
nevracet interní výjimku ani celý citlivý payload v chybové odpovědi a logu
dokumentovat kontrakt přes OpenAPI či jiný zdroj pravdy a změny zavádět kompatibilně
testovat neplatnou syntaxi, chybějící pole, neznámou událost i opakované doručení integrační zprávy

Časté otázky

Co JSON vyjadřuje a co už ne

Je JSON API?

Ne. JSON je formát dat. API navíc určuje endpointy, metody, autentizaci, oprávnění, chybové stavy a význam jednotlivých polí.

Je OpenAPI totéž co JSON?

Ne. OpenAPI je specifikace pro popis HTTP API a lze ji zapsat jako JSON nebo YAML. Obyčejný JSON dokument nepopisuje automaticky celé API.

Mohu v JSONu posílat cenu jako desetinné číslo?

Lze to, ale kontrakt musí určit přesnost a zaokrouhlení. Pro peníze se často používá celočíselná hodnota v nejmenší měnové jednotce nebo přesně definovaný řetězec.

Chrání JSON před útokem?

Ne. Formát neřeší HTTPS, podpis, autentizaci, autorizaci ani validaci business pravidel. Vstup je třeba omezit a ověřit stejně jako jiná nedůvěryhodná data.

Jak pracuji s integračními daty

Datový formát propojuji s kontraktem, validací a bezpečným zpracováním události.

U API, marketplace a e-commerce integrací řeším strukturu zprávy vedle autentizace, idempotence, retry a dohledatelnosti chyb.

Jak pracuji s API a integracemi Nezávazně probrat projekt