When using Application Programming Interfaces (or APIs) through software, it is super critical to receive and transmit data in forms that are standards-based and machine and human readable.
Let’s go over a few reasons why it is so.
Extensible Markup Language (XML) and JavaScript Object Notation (or JSON, pronounced as Jay-sun) and YAML Ain’t Markup Language (YAML) are the main data encoding formats used in remote APIs today. JSON is both a human-friendly and machine-readable format and sends data in name-value pairs. JSON and YAML can be converted to each other without much effort.
JSON is best known for the curly brace syntax. It is popular because it is easier to read and natively maps to Python dictionary data structure. However, XML is bit of an outlier, it is less simple to parse and convert to JSON or YAML. It is an older format so there are plenty of mature APIs that still use it.
Parsing JSON, YAML and XML is a common requirement of interacting with REST APIs.
XML Example
XML is the parent of HTML. It is generic method to wrapping textual data in symmetrical tags to indicate semantics. XML files typically carry an extension of .xml.
The first line in XML file is known as the XML prologue. It has a special format and bracketed by <? and ?>. It contains the tag name xml and attributes stating the version and a character encoding. Normally, you’d find the version to be “1.0” and the character encoding to be “UTF-8” or 8-bit Unicode Transformation Format.
XML files can include comments, much like their HTML counterpart, they are enclosed in <! — and –> tags.
Everything after the prologue is considered to be the XML body. The individual elements are surrounded by symmetrical pairs of tags, the opening tag < and the closing tag > symbols. The closing tag includes a “/” preceding the closing tag.
The main body of the document as a whole is always surrounded by an outermost tag pair, e.g. <root> and </root> in the example.
The structure of an XML document is like a tree with branches (known as elements) containing further branches (known as sub-elements), e.g. <element></element> are elements whereas <gender></gender> are sub-elements.
XML allows you to embed attributes inside the tags to convey additional information. Version and the encoding types in the XML prologue are examples of attributes. Attribute values are carried inside double quotes and an element can have multiple attributes each with a unique name.
Some XML messages or documents incorporate a reference to a specific namespace to convey how they should be consumed. Namespaces are defined by standard bodies such as the IETF, e.g. xml:ns:netconf for NETCONF.
JSON Example
Now, let’s convert above XML into JSON.
JSON data types include numbers, strings, and boolean (True or False). JSON filenames typically end in “.json”.
Much like JavaScript, individual objects comprise of key/value pairs surrounded by braces e.g. {“key”:”value”}.
Objects can also contain multiple key/value pairs, separated by commas, similar to Python dictionaries. JSON values can also contain lists of data objects.
Unlike XML or YAML, JSON doesn’t support adding any kind of comments. JSON format also doesn’t give any significance to white spaces, so you can indent your JSON data using tabs or spaces or nothing at all.
YAML Example
YAML format is like a superset of JSON but even easier to read. One of the most commonly known use of YAML is configuration files and particularly for writing declarative automation templates such as Ansible playbooks. YAML parsers can also parse JSON but not vice versa.
YAML files open with “—” and end with “…”. You can also have multiple YAML documents within one file where each document is separated by “—“. YAML filenames typically end in “.yaml”.
YAML data types include numbers, strings, and Boolean. Strings don’t need to be quoted, quotes are only needed when strings contain characters that have meaning in YAML.
YAML uses indentation to describe hierarchies. Items indented below a label are considered members of that labeled element. There are no specific requirements for indentation amount, you can use a space or a tab. However, the best practice is to use two spaces per indent level.
YAML maps can contain multiple key/value pairs and ordered lists. Maps are expresses over multiple lines, beginning with a label key and a colon, followed by members.
Lists are represented in a similar way, but members are preceded with a hyphen (dash) and a space.
Maps and lists can also be written in flow syntax (much like Python).
Comments in YAML can be inserted anywhere inside the document with the exception of in a long string. All comments are preceded by the hash sign.
Now, let’s convert our JSON document into YAML.
