In the past I’ve seen examples of clever use of style sheets to turn XML responses into browsable results that are human readable and more important; human navigable. But this was the first time I heard about using HTML straight up to create the content of a web service API. It is interesting that there is so much focus of defending HTML as shorter than JSON when I think size should not really be a factor here. Sure, mobile clients want smaller payload but with faster and faster networks and clients with more memory the availability of parser are far more important. but if we can assume that all client have both JSON and XML parsers that is not a deciding factor. I think the most important factor is what the client wants. The linked article mentions that using compressed payload is common and as such it is used as an argument why HTML is not really larger than JSON. But whether or not compression is used is something the clients requests in its request headers. Which content type a client can handled is also an HTTP header so I think it is a no-brainer for a web service to support multiple content types if needed by its clients. Supporting both XML and JSON should be trivial these days and implementing a HTML serializer should be trivial.
I also think the format the author used for HTML was a little bit surprising. My first thought was to convert the example JSON used into something like this:
<html><body> <dl> <dt>contacts</dt> <dd><ol> <li><dt>firstname</dt><dd>Jon</dd><dt>lastname</dt><dd>Moore</dd></li> <li><dt>firstname</dt><dd>Homer</dd><dt>lastname</dt><dd>Simpson</dd></li> </ol></dd> </dl> </body></html>
That even turned out to be slightly smaller than what was suggested in the article. Not that size matters…