Why JSON is Superior to XML for API Docs

Although most developers prefer to use JavaScript Object Notation (JSON) to develop RPC-APIs, a non-trivial number of them continue to use Extensible Markup Language (XML) instead. API developers who do so are not behind the curve on adoption. Instead, they deliberately select XML to develop APIs for security purposes and other reasons.

XML As Cousin to HTML

In the late 1990s, I became heavily involved in hand-coding websites using HTML. The emergence of XML seemed perplexing and wholly unnecessary at first glance. My thought process at the time was simply, "Do we really need to create a system for structuring documents on the web?'

Intrigued, a quick study of XML convinced me why this was the case (who was I to question expert developers). Structuring documents with XML provided the web with a certain uniformity and consistency. And as a technical college librarian, I should have been gung-ho about the idea. However, assuming everyone would use XML in the same way HTML is used was a bridge too far.

That seemed unfortunate at the time. After all, the internet lets users quickly view the ordered tree structure that XML creates for a website (drag the site's XML file over to a new tab). And for the non-developer, XML is far easier to understand object-oriented than programming.

Perhaps the disparity between XML and most programming languages was its downfall. Developers are much more attuned to JSON since represents data within JavaScript. Given that JavaScript is not all that different from other programming languages, using JSON to exchange data is a much more amenable fit (unlike XML-based APIs that require data binding and serialization steps). In short, JSON offers simplicity (no beginning and ending tag) and is superior at parsing data.

Nonetheless, SOAP APIs still rely on XML by design. At times its complexity becomes an advantage. For instance, XML allows users to create user-defined elements and set metadata within a specific data tag using attributes. An XML-RPC can handle a wider range of data, including text, images, graphs, charts, and more. And an XML parser can even validate an XML document with a Schema document as it transfers to another server.

XML also offers better security features than JSON. In addition to supporting more encoding formats, XML provides namespace support and can readily display data. Thus, XML remains the select choice for online entities that value privacy and security.

Concluding Thoughts

Whereas XML focuses on structured documents, JSON focuses on structured data. The difference seems semantic but is utterly critical. Simply put, developers are much more likely to handle structured data than structured documents on a daily basis. Nonetheless, XML will remain an essential tool for a subset of developers for some time to come.