XML a JSON ve webových API

Požadavek a odpověď

Pokud posíláš JSON, nastav Content-Type na application/json a text zakóduj v UTF-8. Hlavička Accept je žádost o formát odpovědi: server kvůli ní nezačne podporovat XML. Stavový kód 415 oznamuje nepodporovaný formát odeslaného obsahu; 406 znamená, že server nemůže nabídnout přijatelný formát odpovědi.

curl --fail-with-body https://example.cz/api/knihy \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data '{"nazev":"XML"}'

Nejdřív HTTP, potom parser

Nejdřív zkontroluj stavový kód HTTP a Content-Type odpovědi. Server může při chybě vrátit HTML stránku, kterou nelze číst jako JSON. Odpověď 204 nemá tělo, proto ji nepředávej JSON parseru. U ostatních odpovědí načti data a ověř jejich strukturu podle schématu. Samostatně kontroluj také pravidla aplikace a oprávnění uživatele.

JSON, REST a SOAP

JSON není totéž co REST. REST API může používat JSON i XML. SOAP používá XML zprávy s vlastní předepsanou strukturou. Při komunikaci se serverem se řiď dokumentací jeho API: ta určuje přijímaný formát, povinné údaje a podobu odpovědi.

Mezi vlastními službami se místo REST používá také gRPC s binárními zprávami Protocol Buffers. Kdy se vyplatí a jak se v něm pracuje s JSON, popisuje srovnání REST s JSON, nebo gRPC.

Spolehlivá integrace

Udržuj dokumentaci a schémata pro každou podporovanou verzi API. Nastav, jak dlouho klient čeká na odpověď a jak velkou zprávu přijme. Před opakováním neúspěšného požadavku ověř, zda tím například nevytvoříš objednávku podruhé. Rozlišuj chybějící hodnotu, null a nulu. Skutečné kódování XML musí odpovídat deklaraci v dokumentu i údajům v HTTP hlavičkách. Citlivá data z odpovědí nezapisuj do veřejně přístupných záznamů.

Úplná výměna JSON a XML přes HTTP

POST /api/knihy HTTP/1.1
Host: example.cz
Content-Type: application/json
Accept: application/json

{"nazev":"XML"}

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/knihy/1

{"id":1,"nazev":"XML"}

POST /api/knihy HTTP/1.1
Host: example.cz
Content-Type: application/xml; charset=utf-8
Accept: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<kniha><nazev>XML</nazev></kniha>

HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8

<kniha id="1"><nazev>XML</nazev></kniha>

Content-Type v požadavku popisuje odesílaný obsah, v odpovědi obsah vrácený serverem. Accept požadavku uvádí požadovaný formát odpovědi. Zda server přijímá stejný formát i na vstupu, zjistíš v dokumentaci API. JSON používej v UTF-8, u XML musí skutečné bajty odpovídat přenosovým metadatům a deklaraci. application/json nemá definovaný charset parametr; application/xml jej má.

Přípony +json a +xml označují strukturovanou syntax, například application/problem+json nebo application/soap+xml. Obecný parser syntaxe je může přečíst, ale aplikace musí znát jejich datový model. MIME typ není důkaz důvěryhodnosti obsahu. Autoritou pro přenos jsou HTTP Semantics a XML Media Types.

Lokální JSON API a klient

import http from "node:http";
const server = http.createServer((req, res) => {
  if (req.method !== "GET" || req.url !== "/knihy/1") {
    res.writeHead(404, {"Content-Type":"application/json"});
    res.end(JSON.stringify({zprava:"Nenalezeno"}));
    return;
  }
  res.writeHead(200, {"Content-Type":"application/json"});
  res.end(JSON.stringify({id:1,nazev:"XML"}));
});
server.listen(8080, "127.0.0.1");

const response = await fetch("http://127.0.0.1:8080/knihy/1", {
  headers: {Accept: "application/json"},
  signal: AbortSignal.timeout(5000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
if (response.status === 204) {
  console.log("Bez obsahu");
} else {
  const media = (response.headers.get("content-type") ?? "")
    .split(";", 1)[0].trim().toLowerCase();
  if (media !== "application/json") throw new Error("Neočekávaný typ odpovědi");
  const data = await response.json();
  if (!Number.isInteger(data.id) || typeof data.nazev !== "string")
    throw new Error("Neočekávaná struktura");
  console.log(data.id, data.nazev);
}

Spusť server v jednom terminálu a klienta v druhém. Výsledek je 1 XML. Změň cestu na /knihy/2: klient skončí chybou HTTP 404 před čtením dat. Jde o malý učební příklad, který neřeší autentizaci ani obecnou validaci. Pro skutečnou aplikaci přidej validaci podle schématu a omez velikost odpovědi už během jejího přijímání. Kontrola až po načtení celého těla nezabrání vyčerpání paměti.