Which API Data Format Is the Best? JSON Vs. XML

At first glance, many might think that communication between computers or programs is simple. “They just talk in 1s and 0s” right? Well, not quite. That’d be like saying that humans communicate by making noises with their mouths. You’d be ignoring the fact that one set of noises is the English language, while another is French, and the particularly screamy noises are German and so on.

Point is, even computer programs can use different languages for communication. Application programming interfaces are meant to bridge the gap between various programs, to ensure that the data crosses the language barrier.

For people, someone who facilitates communication, like a translator, will understand several languages or “formats” and send information in the preferred format of the listener. While you’ll see format preferences in computer programs as well, their solution is more along the lines of choosing a few designated data formats to use for all communication.

For APIs, the most widely used and well-known data formats are JSON and XML. The burning question is which is better?

The answer depends on what you want to do with your API because there’s no absolute winner. Let’s look at the characteristics of each format, and you be the judge of which one would fit better into your plans.

XML, the tried and tested option

XML stands for Extensible Markup Language and yes, reader, the name does imply that it’s a markup language, not a format. Very astute of you to notice that. While XML started off as a language, its success meant that it is also used as a way to structure transferable data. Most old APIs you’ll run into use XML files to transfer data.

While XML syntax can seem a bit outdated and intimidating at first, it’s actually quite easy to understand. The bedrock of an XML file is built by the nodes it has. Each piece of info is found within a node that defines what that information represents. The primary node is called the root and acts as the parent to all other nodes. Those can, in turn, have their own children and so on.

So, how does an XML file look like in real life? Well they can get pretty long so we’ll show you the syntax with a simplified example: an iPhone 7’s specs (note that we’ll be skipping many details for brevity):

<iphone7>
    <manufacturer>Apple</manufacturer>
    <os>ios 10.0.1</os>
    <dimensions>
        <length>138.3</length>
        <width>67.1</width>
        <heights>7.1</heights>
    </dimensions>
</iphone7>

XML has been in use for many years, and plenty of developers are used to it. Still, the format could be bulky and cause too much overhead for web services. The need for a simpler and more lightweight data format has led to the quick rise of XML’s rival, JSON.

JSON, the new and breezy format

JSON stands for JavaScript Object Notation. As you no doubt noticed from the name, its structure is based on the JS programming language. It’s a lot more versatile both for data transfer and parsing since it’s supported by several data structures.

Most modern web services use JSON as a data exchange format due to the speed and agility it offers. As such, some see JSON as XML’s successor. For web APIs, it might be true, but that’s not to say that JSON is simply better than XML.

Whereas XML is all about nodes, JSON is defined by its key-value pairs. The system is pretty simple, even if you don’t know anything about Javascript. You use a key to define what a piece of data represents and then give it a value. For the aforementioned iPhone 7 example, the JSON file would look like this:

{
  “manufacturer”: “ “apple”,
  “os”: “ios 10.0.01”,
  “dimensions”: {
    “length”: “138.3”
    “width”: “67.1”
    “heights”: “7.1”
  }
}

Additionally, if we weren’t interested in what each dimension represents, we could just as easily add all three numbers to an array and set that as the value for the “dimensions” key. With XML, that wouldn’t be an option. A bit of extra simplicity goes a long way when you’re sending thousands of requests and responses through an API every single day. But besides the syntax, what are the differences between the two formats?

JSON Vs. XML, a battle of use cases

JSON’s simple syntax and structure mean that you can fit in more information in less space. So, data transfers happen faster, and parsing is easier, especially since JSON is built on the JavaScript programming language.

On the other hand, while XML is a lot bulkier due to all its tags and nodes, it does offer a clearer structure of what each value or piece of data represents. If your API will deal with complex information that has plenty of details and parameters, XML begins to look like a better and better option.

For web services or APIs in general, it comes down to what the average data transfer looks like. Are you sending simple data and just want to do it as fast and efficiently as possible? Then pick JSON.

Are you sending large files with very many details that need to be clearly specified and understood? Then you might want to stick to XML, especially if the data itself will create some overhead.

For pre-existing software, it might accept both types or maybe even neither. When you make a request with data in the body, a header you can use is the “Content-Type” to let the server know what kind of file you’re sending. For example, if you’ve added a JSON file, the header will have “application/JSON” as its value.

If the client is asking for data instead, then the request can contain the header “Accept”, which defines what kind of data format will be accepted by the client. If the server can’t accommodate the format preference, it will send an error message and let the client know.

So, it’s not only a matter of speed vs. data complexity. You should also take into account which kinds of data are currently supported by the client or server. Choosing the appropriate format can make a big difference in operational speed and overhead, but you can’t deny that remaking the whole system from the ground up would also be a taxing undertaking.

If you’re still a bit unsure about how JSON and XML fit into the overall structure or role of APIs, you should definitely read my previous article on the topic of HTTP and its protocol.