JSON, XML & the Format Transition

Two ways to structure data in HTTP bodies

When an API returns or accepts structured data, the bytes in the body need a format both sides understand. For decades that meant XML. Today most new APIs use JSON. Hosting teams still bump into both — especially when wiring old accounting software, RSS feeds, or enterprise tools into modern automation.

JSON — the default for modern APIs

JSON maps cleanly to objects in Python, PHP, JavaScript, and Go. Workshop Co.'s booking API (from the previous chapter) is typical:

{
  "classes": [
    {"id": "intro-wood", "title": "Intro to Woodworking", "seats_left": 4},
    {"id": "box-joint", "title": "Box Joint Masterclass", "seats_left": 0}
  ]
}

Rules that trip up beginners:

• Keys and string values use double quotes — not single quotes
• No trailing commas after the last item in an array or object
• null, true, and false are lowercase (not strings)
• Numbers are unquoted: 4 not "4"

XML — tags, attributes, and namespaces

XML wraps data in nested elements. The same class list might look like:

<?xml version="1.0" encoding="UTF-8"?>
<classes xmlns="https://workshopco.ca/schema/v1">
  <class id="intro-wood">
    <title>Intro to Woodworking</title>
    <seats_left>4</seats_left>
  </class>
  <class id="box-joint">
    <title>Box Joint Masterclass</title>
    <seats_left>0</seats_left>
  </class>
</classes>

XML strengths that kept it alive for years:

• Schema validation — XSD files define allowed structure (useful in regulated industries)
• Namespaces — mix vocabularies in one document without name collisions
• Tooling — XSLT transforms, digital signatures, enterprise middleware built around it

Downsides for everyday API work: verbose payloads, slower to hand-edit, and easy to get wrong with unclosed tags or encoding issues.

The transition — why JSON won

Between roughly 2005 and 2015, the industry shifted from SOAP/XML services to REST/JSON. The drivers were practical, not ideological:

SOAP (Simple Object Access Protocol) wrapped XML in a rigid envelope with WSDL contract files. It worked for bank-grade integrations but felt like flying a 747 to pick up groceries. REST over HTTP with JSON bodies became the default for “call this URL, get this object back.”

Content-Type tells you what you received

Always check the response header before parsing:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"status": "ok"}

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<response><status>ok</status></response>

Some servers mislabel bodies (JSON returned as text/plain). If parsing fails, inspect the first character: { or [ suggests JSON; < suggests XML/HTML.

Worked example — same data, two formats

Workshop Co. wants to sync class availability to a legacy newsletter tool that only accepts XML, while their new website posts JSON to a webhook.

Incoming JSON webhook (modern contact form aggregator):

POST /hooks/class-update
Content-Type: application/json

{"class_id": "intro-wood", "seats_left": 2, "updated_at": "2026-05-31T14:00:00Z"}

Outgoing XML feed (legacy partner):

<classUpdate>
  <classId>intro-wood</classId>
  <seatsLeft>2</seatsLeft>
  <updatedAt>2026-05-31T14:00:00Z</updatedAt>
</classUpdate>

Marcus's script: json_decode() the webhook body → transform fields → build XML string (or use a small library) → POST to the partner. The translation layer is the pattern hosting teams use when bridging old and new systems.

Migration checklist — XML API to JSON

1. Inventory callers — which cron jobs, plugins, or scripts still hit the XML endpoint?
2. Run parallel — expose JSON alongside XML during transition; log both formats
3. Map fields 1:1 — document renamed keys (seats_left vs seatsLeft vs <seats_left>)
4. Update auth — legacy SOAP often used WS-Security; JSON APIs usually use Bearer tokens (next chapter)
5. Cut over — lower TTL on DNS if the endpoint hostname changes; monitor error rates for 48 hours
6. Retire XML — remove WSDL/XSD docs from internal wiki once traffic hits zero

curl -sI https://swifthost.ca/sitemap.xml | grep -i content-type
curl -s https://swifthost.ca/sitemap.xml | head -20