Why you should use XML for your API

class: center, middle

# Why you should use XML for your API

---
# XML, YAML, JSON

## Lots of choices
* YAML is easier to read/write
* JSON is easier to parse
* Why XML?

> If I have seen further, it is by standing on the shoulders of giants.
>
> Isaac Newton
---
# Data Validation

Your API has restrictions on allowed values. Base types like string, decimal, float, array, associative array are usually too broad.

**Enumerated Type**
```
<xs:simpleType name="US_STATE">
  <xs:annotation>
    <xs:documentation xml:lang="en">US STATES</xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:enumeration>AK</xs:enumeration>
    <xs:enumeration>AL</xs:enumeration>
    ...
  </xs:restriction>
</xs:simpleType>
```
--

**Regex**
```
<xs:simpleType name="US_ZIP4">
  <xs:restriction base="xs:string">
    <xs:pattern value="[0-9]{5}(-[0-9]{4})?"/>
  </xs:restriction>
</xs:simpleType>
```
---
# Data Validation - cont

**Integer Range**

```
<xs:simpleType name="CONTROL_RANGE">
  <xs:restriction base="xs:integer">
    <xs:minInclusive value="-1"/>
    <xs:maxExclusive value="10"/>
  </xs:restriction>
</xs:simpleType>
```
--
**Decimal Range**

```
<xs:simpleType name="OUTPUT_LEVEL">
  <xs:restriction base="xs:decimal">
    <xs:fractionDigits value="2"/>
    <xs:minInclusive value="-0.05"/>
    <xs:maxExclusive value="0.05"/>
  </xs:restriction>
</xs:simpleType>
```
---
# Data Validation - cont 2
**Key and Key Reference**
```
<xs:key name="idUser">
  <xs:selector xpath="./users/user"/>
  <xs:field xpath="name"/>
</xs:key>

<xs:keyref name="groupToUser" refer="idUser">
  <xs:selector xpath="./founders/founder"/>
  <xs:file xpath="."/>
</xs:keyref>
```
Validation will confirm that keys are unique and keyrefs refer to a valid key.
---
# Namespaces

> There are two hard things in computer science:<br/>
>  cache invalidation<br/>
>  naming things<br/>
>  off-by-one errors.

All the good names are taken.
Namespaces allow you to reuse names while providing a context for disambiguation.

```
<users>
  <ns1:user name="John Doe"/>
  <ns2:user>
    <name>Jane Roe</name>
  </ns2:user>
</users>
```
---
# XPath

Foundamental syntax for identifying nodes or node sets in an XML document:
--

### All key Elements with value 'one' in the current context
key[. = 'one']

* leading / ties the hierarchy to the root
* leading // looks anywhere in the document
* nothing looks anywhere in the current context

### All key Elements with phase attribute 'two' that are children of /root/collection
/root/collection/key[@phase = 'two']

---
# XSLT
### Extensible Stylesheet Language Transformations

A language for transforming XML documents into other XML documents or other
formats (html, plain text, PostScript, ...).

Of particular interest for API work is providing a formatted display of the
raw data. For example [transform.xml](http://demo.ideoplex.com/transform.xml)
can be served to a browser as XML and transformed in the browser to html.
---
# XQuery

Back in the day, databases were "structured data" and documents were "unstructured data".
XML documents were neither fish nor fowl -
clearly structured, but without a query language.
Enter XQuery - a query language for XML document sets.

See [XQuery in 10 Minutes](http://www.stylusstudio.com/xquery-primer-new.html)

See [BaseX](http://basex.org/)
---
# Why you should XML for your API

1. Validation - standard tools to define allowed data values and validate data against that definition
1. Namespaces - standard syntax to combine elements from multiple sources in a single document
1. XPath - standard language to identify specific nodes or nodes sets in a document
1. XSLT - standard tools to extract and transform xml data
1. XQuery - standard tools to query xml data

<br/>
> Horses for Courses

JSON is getting some of these things, but XML has mature implementations