Quick answer: For most new web and mobile APIs in 2020, JSON is the default: lighter, easier in JavaScript, and widely supported. XML still fits document-centric systems, enterprise SOAP estates you must integrate with, publishing workflows and standards that already mandate it. Choose based on clients, ecosystem and schema needs, not fashion. Many organisations expose JSON for modern apps while still speaking XML to legacy partners.
What each format is
JSON (JavaScript Object Notation) expresses objects, arrays, strings, numbers, booleans and null in a compact text form. It maps naturally to structures in JavaScript, and libraries exist for every major language.
XML (eXtensible Markup Language) expresses trees of elements with attributes, namespaces and mixed content. It grew up with documents and enterprise messaging. XSD schemas, XPath and XSLT give it a mature validation and transformation toolkit.
If you are new to APIs generally, start with what is an API and REST API design before debating encoding.
Size and parsing
JSON payloads are usually smaller than equivalent XML because there are no repeated closing tags. On mobile networks that matters. Parsing JSON in browsers is native and fast (JSON.parse). XML parsing in browsers works but is less pleasant for typical REST resource APIs.
On the server, both parse quickly enough when used sensibly. Giant deeply nested documents hurt either way; design lean resources.
Tooling and developer experience
Front-end and mobile developers expect JSON. Most public HTTP APIs document JSON examples. Tools like Postman, browser devtools and OpenAPI examples lean JSON by default. See OpenAPI specification and API documentation habits that keep consumers productive.
XML shines when you already have XSD contracts, SOAP stacks, industry standards (many finance, healthcare and publishing flows) or need careful namespaces. Enterprise ESBs often assume XML.
Schema and validation
JSON Schema exists and is useful, though the XML/XSD world is older and in some industries more standardised. If your compliance process already ships XSDs, fighting that with JSON adds mapping work. If you build a greenfield SaaS API for web apps, JSON Schema or type definitions in OpenAPI are usually enough.
Attributes vs structure
XML allows attributes and element text; modelling the same ideas in JSON means nested objects and arrays only. That is fine for most APIs. Document formats with mixed text and markup (think articles with inline formatting) remain more natural in XML.
Security notes
Both need care: XML has historical XXE (external entity) attack classes if parsers are misconfigured; JSON has injection risks when unsafely embedded into HTML or evaluated as script. Use safe parsers, never eval JSON, and follow API security basics either way. Size limits and authentication matter more than the acronym on the wire.
Content negotiation
HTTP APIs can support both with Accept headers (application/json, application/xml) when you must. Dual formats double test burden. Offer both only while migrating. Prefer one public format for new external APIs.
SOAP vs JSON-over-HTTP
People sometimes say “XML” when they mean SOAP. SOAP envelopes, WS-* policies and WSDL are a whole stack. Replacing a SOAP service with JSON REST is a project, not a mime-type swap. Plan mapping, authentication differences and partner timelines carefully. Custom API development teams often build anti-corruption layers that speak SOAP upstream and JSON downstream.
Practical decision guide
Pick JSON when:
- Clients are web browsers, mobile apps or Node services
- You want minimal payload size and simple debugging
- You document with OpenAPI and example objects
Pick XML when:
- Partners mandate it
- You rely on XSD/XSLT already
- The data is document-like with mixed content
- You are extending an existing XML interface
Pick both only with a clear retirement date for one of them.
Examples in spirit (illustrative)
A person resource in JSON looks like a nested object with id, name and email fields. The XML cousin wraps the same fields in elements, optionally with a namespace. Teams argue less about braces versus angle brackets than about field naming, versioning and error shapes. Spend design time there.
Migration tactics
When moving XML APIs to JSON:
- Model resources, do not blindly transliterate every tag
- Version the new API (
/v2/) rather than breaking old clients - Provide a mapping guide for partner developers
- Run both until traffic shifts
- Monitor errors by format
Modern headless and JAMstack-style stacks almost always emit JSON to the front end, even if editors store richer structures behind the scenes.
Human readability and support
Support engineers paste payloads into tickets. JSON tends to be quicker to skim for nested resources. XML can be clearer for document trees with attributes. Pretty-printing and schema-aware editors exist for both. Pick the format your support and partner teams can debug at 2am.
Versioning payload fields
Whether JSON or XML, never reuse a field name with a new meaning. Add fields, deprecate carefully and document. Content type alone does not version your API; URLs or explicit version headers do.
Error formats
Agree on an error shape early. JSON APIs often use a body with error, message and code. XML APIs may use standard fault elements in SOAP or custom error elements in REST-like XML. Consistency matters more than which style you copy.
Testing contracts
Contract tests should assert status codes, content types and critical fields. For public APIs, publish example payloads in both happy and error paths. Consumer-driven contract testing helps when many clients depend on you.
Internationalised content
UTF-8 JSON handles global text well when declared correctly. XML with proper encoding declarations does too. Problems appear when legacy systems emit other encodings or when databases store mojibake. Normalise on UTF-8 across every layer.
Browser and mobile clients
Browser apps speak JSON natively. React, Vue and Angular examples in 2020 almost always assume JSON REST or GraphQL JSON responses. Native mobile apps likewise parse JSON with standard libraries. Asking those clients to consume XML adds conversion layers and irritation.
If your only clients are enterprise middleware tools that already ship XML adapters, the calculus flips. Meet the clients you have, not the ones imagined in a textbook.
GraphQL aside
GraphQL typically returns JSON. It does not make the JSON vs XML debate irrelevant for your other HTTP endpoints, but it does show where the broader ecosystem settled for app UIs. You can still offer XML for a legacy partner beside a GraphQL API for the product UI.
FAQ
Is JSON replacing XML everywhere?
In public web APIs, mostly yes. In enterprise document exchange, XML remains common.
Is JSON less “enterprise” than XML?
No. Large enterprises run plenty of JSON services. Enterprise fit is about contracts, ops and security, not the pretty-print format.
Can I compress either?
Yes. HTTPS with gzip/deflate (and newer encodings where supported) shrinks both. Compression does not remove the need for lean models.
What about Protocol Buffers or MessagePack?
Binary formats help internal high-throughput services. For public HTTP APIs that humans debug, JSON still wins most debates in 2020.
Choose for clients, not nostalgia
JSON vs XML is a product decision: who consumes the API and what tooling they trust. Default to JSON for new web APIs, keep XML when the ecosystem demands it, and document either choice clearly. If you need APIs designed and built for your stack, see our Custom development service.
