Why Consistency Matters Across the Media Types Offered by an API

Continued from page 1. 

If you inspect the Weather Underground's JSON response closely, you'll see that it offers the current temperature with three different key:value pairs virtually every human will understand:

"temperature_string":"57.9 F (14.4 C)",

In contrast, the OpenWeatherMap API offers the following key:value pair by default:

"temp": 289.2

So, what's happening here? Whether celsius or fahrenheit, if the temperature in Union Square in San Francisco is 289.2, everyone there would be reduced to ashen cinder. That can't be right, can it?

For kicks, I switched the Content-Type for OpenWeatherMap's response from JSON to XML using the following URL string:

http://api.openweathermap.org/data/2.5/weather?zip=94107&mode=xml&APPID=<<David's API key for OpenWeatherMap>>

and here's what I got:

<city id="5391959" name="San Francisco">
<coord lon="-122.42" lat="37.77"/>
<sun rise="2016-08-29T13:38:19" set="2016-08-30T02:41:22"/>
<temperature value="289.34" min="286.15" max="300.15" unit="kelvin"/>
<humidity value="72" unit="%"/>
<pressure value="1020" unit="hPa"/>
<speed value="5.1" name="Gentle Breeze"/>
<direction value="280" code="W" name="West"/>
<clouds value="90" name="overcast clouds"/>
<precipitation mode="no"/>
<weather number="500" value="light rain" icon="10d"/>
<lastupdate value="2016-08-29T16:42:03"/>

Notice anything?  More specifically, the following field for current temperature:

<temperature value="289.34" min="286.15" max="300.15" unit="kelvin"/>

When OpenWeatherMap returns the temperature as part of it's default JSON payload, it offers the current temperature, the minimum, and the maximum.  But when you switch the OpenWeatherMap response to the optional XML payload, not only was the data organized differently, there was an additional field of data called "unit"" and it contained "kelvin"; a minor but important detail that's missing from the JSON payload. 

In fairness to OpenWeatherMaps, its API documentation says that "kelvin" is the default temperature representation for API responses. To switch to fahrenheit or celsius, the following URL strings would work:

fahrenheit: http://api.openweathermap.org/data/2.5/weather?zip=94107&units=imperial&APPID=...

celsius: http://api.openweathermap.org/data/2.5/weather?zip=94107&units=metric&APPID=...

Even so, Allen's point is not only easily made between different offerings within the "weather reports" subject matter domain (the offerings from OpenWeatherMap and Weather Underground are very different), it's literally made within the same physical domain (opendatamaps.org) where the data is a tad more easily interpreted in one format (XML) than the other (JSON).  There's no reason the same informative bit of data (units) could not have been included in the JSON payload. 

So, is this a big deal? Or a big to do about nothing? To the extent that there are subject matter schema standards like schema.org, I agree that the more API's can conform to those standards, the easier it will be for machines to deal with the dynamic nature of certain APIs. But for developers and humans, even though there's a lot to be said for great documentation, the aforementioned weather examples which took me an extra two minutes to figure out would not have impeded my progress as a developer. That said, at bare minimum, there's something to be said for offering a consistent schema across the various possible serializations like XML and JSON. 

David Berlind is the editor-in-chief of ProgrammableWeb.com. You can reach him at david.berlind@programmableweb.com. Connect to David on Twitter at @dberlind or on LinkedIn, put him in a Google+ circle, or friend him on Facebook.




Nice post. From the article I understand that consistency should be maintained by a REST based API when it supports two different content-types like json and xml. The weather report in json and xml is not consistent as shown in the example. I get this point. What I didn't follow is this statement - "The client gets absolutely no information about how to read the data, other than they'll need a JSON decoder"

What should the API developer do other than maintaining consistency between supported media/content types? 



Hi @shahmit and thanks for your feedback. That quote came from the article on DZONE. I tried my best to figure that out. What was clear is that author was frustrated and so I just decided to test his theory. In answer to your question, I believe it is too open-ended of a question.  There are probably tens if not hundreds of things that an API developer should do as a matter of best practices above and beyond maintaining consistency betweeen supported media/content types. For example, publicly exposing the OAS, RAML, etc. definition file(s) of their APIs.