Media Types

What is a Media Type?

In the same way that humans have developed shared languages to facilitate communication, the internet has given rise to a set of shared markup languages and data formats for transferring information between computers. One example of this is HTML, the markup language used to create all web pages, including this one. Because nearly all computers (and now most phones, tablets, and even televisions) can understand HTML and display it, the web is extremely accessible for people using a wide range of devices.

HTML is one of many different media types (also called content types or sometimes MIME types) supported by modern web browsers. It is represented in an HTTP response as the Content-Type header as text/html:

Content-Type: text/html

This tells the browser to interpret the content as HTML and render it graphically on the screen.

Most web servers also include a charset for certain text media types, so a real world response header would look more like this:

Content-Type: text/html; charset=UTF-8

The charset (or character set) tells the browser which set of characters the response is using. The charset for most requests will be UTF-8 or ISO-8859-1. For the purposes of this book, and for the work we'll be doing with APIs, we don't need to get into the difference between these or other character sets. If at some point you are seeing strange characters when working with an API, you should check the response charset to make sure it is something compatible with the tools you are using.

Other media types include text/plain for plain text responses, text/css for CSS stylesheets, application/javascript for JavaScript files, and many, many more. There are media types for PDF documents, sound files, videos, ZIP archives, and many, many, more.

It is possible to use HTTPie to look at the content type of a variety of URLS and see some of the different media types. Using the --headers switch tells httpie to only print out the response's headers (in the following listings, some headers have been omitted for brevity):

$ http --headers www.google.com
HTTP/1.1 200 OK
Alternate-Protocol: 80:quic,p=0.002
Cache-Control: private, max-age=0
Content-Type: text/html; charset=ISO-8859-1
Date: Fri, 19 Sep 2014 18:36:13 GMT
Expires: -1
Server: gws
Transfer-Encoding: chunked
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block

The Google homepage has a media type of text/html, which makes sense: it is a basic web page.

Many other parts of the web are built with text as well, such as the CSS used to tell a browser how to display HTML. Google Fonts provides CSS files that enable browsers to display text in specific fonts using the media type text/css:

$ http --headers http://fonts.googleapis.com/css\?family=Open+Sans
HTTP/1.1 200 OK
Alternate-Protocol: 80:quic,p=0.002
Cache-Control: private, max-age=86400
Content-Length: 244
Content-Type: text/css
Date: Fri, 19 Sep 2014 18:47:16 GMT
Expires: Fri, 19 Sep 2014 18:47:16 GMT
Server: GSE
Timing-Allow-Origin: *
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block

The media type returned by loading a photo URL from Flickr is image/jpeg, which tells the browser to display the response's body as an image.

$ http --headers https://c2.staticflickr.com/4/3913/15095210318_930069f3d6_c.jpg
HTTP/1.1 200 OK
Accept-Ranges: bytes
Age: 72701
Cache-Control: max-age=315360000,public
Connection: keep-alive
Content-Length: 311944
Content-Type: image/jpeg
Date: Fri, 19 Sep 2014 02:26:32 GMT
Expires: Wed, 18 Sep 2024 10:35:21 UTC
Last-Modified: Thu, 18 Sep 2014 21:22:48 GMT
Server: ATS
X-Cache: HIT from photocache429.flickr.gq1.yahoo.com
X-Cache-Lookup: HIT from photocache429.flickr.gq1.yahoo.com:81

Data Serialization

APIs are generally used to allow systems to communicate by passing structured data back and forth. The content of most requests will use a format and media type that works well for representing hierarchical data. These formats are known as data serialization formats.

A data serialization format describes a way for programs to convert data into a form which is more easily or efficiently stored or transferred. The stored or transferred data can then be converted back into the original data at any time by the original program or any other program that can understand its format.

In 1915, the artist Kazimir Malevich created his now well known piece Black Circle to go along with his manifesto From Cubism to Suprematism . It looks like this:

Kazimir Malevich's Black Circle, 1915

Now let's imagine a world where Malevich was born one hundred years later, in 1979 instead of 1879. In this reality, it is conceivable that Black Circle would have been created in a vector graphics program instead of on canvas. In this world, it looks more like this:

A vector version of Black Circle

When it came time for Malevich to save his creation to a disk or perhaps send it to another system, the graphics program might save a representation of the circle into a file using some SVG code:

<svg viewBox="0 0 55 54">
  <circle cx="32.5" cy="22" r="21.3" fill="black"/>
</svg>

This SVG code is written using XML, which is an older data serialization format that is sometimes used by APIs. By serializing data that represented the circle, the drawing program could more easily store the information or transfer it to another system. The data could also be read back into another application, which could display the circle on the screen, send it to a printer, or allow a user to make additional modifications.

XML

XML (or extensible markup language) shares common heritage with HTML: they are both based on an earlier and similar type of markup, SGML. XML is generally stricter than HTML and doesn't handle missing tags or improper nesting. It was fairly common to see XML used with APIs in the past, and while some services continue to support XML, JSON has become much more common.

Here is one way to represent an address in XML:

<address>
    <street>1600 Pennsylvania Ave NW</street>
    <city>Washington</city>
    <state>DC</state>
    <zipcode>20500</zipcode>
    <country>Unites States</country>
</address>

JSON

JSON (or JavaScript Object Notation) is perhaps the most popular data serialization format used by web APIs today. The syntax JSON uses is based on the way object literals are written in JavaScript, the ubiquitous scripting language of the web. While JSON's popularity is partially due to being based on existing web technologies, a distinction it shares with XML, it is also the result of JSON being a simpler and less ambiguous format.

A simple JSON document is used to represent key and value pairs. Here is one way to represent a US address as JSON:

{
  "street": "1600 Pennsylvania Ave NW",
  "city": "Washington",
  "state": "DC",
  "zipcode": "20500",
  "country": "United States"
}

JSON can represent objects, arrays, strings, and numbers:

{
  "object": {
  	"city": "Boston"
  },
  "array": [1, 1, 2, 3, 5],
  "string": "Hello, World!",
  "number": 8675.309
}

We will be using JSON exclusively in this book. The tools we use will create most of the JSON for us, so we won't be writing it manually. Being able to reference specific values with a JSON structure, however, will be useful.

Given the following JSON data:

{
  "menus": {
    "breakfast": {
      "toast": 1,
      "coffee": [1.25, 1.75, 2.25]
    },
    "lunch": {
      "sandwich": 6.50,
      "soup": [4, 5],
      "salad": 7
    }
  }
}

We could say that the value at menus.breakfast.toast is 1 and the value at menus.lunch.soup[0] is 4.

Summary

Media types describe the format of a response's body.
Media types are represented in an HTTP response's Content-Type header, and as a result, are sometimes referred to as content types.
Data serialization provides a common way for systems to pass data to each other, with a guarantee that each system will be able to understand the data.
JSON is the most popular media type for web APIs and the one this book will focus on.