REST API, why no HTML instead of JSON? - html

Question

This is probably a stupid idea, but I would like to know why.
I'm reading about REST API's, and principles such as HATEOAS. All the time, I'm wondering why people don't just use HTML for the representation of their resources.
Sure, I can think of disadvantages such as parsing difficulties and increased data, but on the other hand, it's a semantical hypermedia language with which you can separate data from presentation. Also, it's human readable and people can interact with it in the browser, follow links, submit forms, etc. It could be used as both an API and UI.
Can anyone explain why it is a terrible idea to use HTML for REST API representations?

Answer 1

The www uses html for REST!
There's nothing wrong with the idea at all. Personally I would congratulate you on your questioning this in the first place, many don't.
Rest does not mandate an application protocol, it's just that JSON/XML has become the standard choice (as HTML is usually hard to parse). If you use a simplified version of HTML you might actually find it more useful than JSON.
I've written several rest applications that accept both application/json and text/html for content negotiation. It allows for easy testing on a browser.
As you mention, it certainly makes HATEOAS easier!
JSON does not (currently) have a standard mechanism for dealing either with HATEOAS or with strong typing (most people use the #class way of specifying what object the json represents). JSON is in my opinion, not finished yet.
XML on the other hand is.. but what is HTML if it isn't a kind of XML?
With html :
<div name="Elvis Presley" id="1" class="com.graceland.elvis.Person">
wife
<span name="country" class="java.lang.String">USA</span>
</div>
Good luck trying to replicate that with Json. Json doesn't effectively handle 'attributes' for starters!

Answer 2

Can anyone explain why it is a terrible idea to use HTML for REST API
representations?
Yes
It is not well formed
How would clients parse the result consistently ?
The markup is verbose
It is not a format meant for consumption by machines. It is a view for humans. REST APIs are meant for machine consumption.
Large responses are bloated and would lead to more network latency.
As for presentation, you cannot assume that the API would be consumed by a browser. What about native Android / iOS apps ?

Answer 3

REST supports all kinds of content included HTML. It's clear that most of RESTful applications and Web APIs are focused on data. So such formats like JSON, XML and YAML are more convenient to build and parse.
But if you want to leverage the Conneg feature (content negociation - based on the header Accept) of REST, you can handle several kinds of content according to the caller:
a browser. Perhaps we would prefer to display an HTML content to display UI for the request. You would have: Accept: text/html.
an application. In this case, you rather expect some structured data. You would have something like that: Accept: application/json, Accept: application/xml, and so on.
In fact, it's up to the RESTful applications. I built RESTful applications that implement conneg and send back several kinds of content according the specified header Accept.
Hope it helps,
Thierry

Answer 4

REST is about communication between machines. HTML contains a lot of GUI elements, it contains CSS, JS, etc... as well. All of these are for humans to display the view. The machines are interested only in the data and its annotation.
Btw. it is possible to use HTML as a data transfer format by REST. For example HAL has (or just had?) a HTML serialization format and Hydra can use HTML as well e.g. with microdata.
If you are talking about HTML which can be used both by the browsers and the REST clients (which extract only the data), then I think it is usually hard to write such a HTML document.

Answer 5

tl;dr: If we assume that XML isn't a terrible idea for a REST API, I think it would be reasonable to use a strict subset of XHTML (JSON is a strict subset of JavaScript), especially if HATEOAS is important to your API.
The fundamental benefit of HTML for a REST API is the <a href=""> and the <form action=""> tags (you can possibly even simplify it down to just the form tag). It's defined to handle Hypermedia and it's the only well understood way of linking documents. You don't have to read a JSON-LD / HAL / Siren spec to understand the structure of the HTML.
Other's here argue against it because HTML contains <h1> tags. But you can use a strict subset of HTML rather than trying to create a superset of JSON. JSON is effectively a strict subset of JavaScript objects. Personally I think this would make an excellent REST API - easy to understand by both humans and machines.
I initially thought that microdata is close to what you want but that only handles the GET for HTTP, you need methods for handling all the other HTTP methods (hence the need for the <form> tag). If you do only care about GET requests I think that might work for you. You asked about JSON-LD in one of your comments and in the Schema.org wikipedia page you can see the similarity between micro data and JSON-LD.
microdata
<div itemscope itemtype="http://schema.org/Movie">
<h1 itemprop="name">Avatar</h1>
<div itemprop="director" itemscope itemtype="http://schema.org/Person">
Director: <span itemprop="name">James Cameron</span>
(born <time itemprop="birthDate" datetime="1954-08-16">August 16, 1954</time>)
</div>
<span itemprop="genre">Science fiction</span>
Trailer
</div>
JSON-LD
<script type="application/ld+json">+schema app
{
"#context": "http://schema.org/",
"#type": "web master",
"name": "schema.org/person",
"Struturedata":
{
"#type": "Person",
"name": "chema mpnrroy josepinedamonroy",
"birthDate": "10/19/1982"
},
"geng": "male",
"Mecanismo":microdata. ".estructuredate./" validador
}
</script>
I think the major issue is that HATEOAS doesn't provide enough tangible benefit to developers, they just want to transfer data not have a self-discoverable API. The self-discovery just isn't that important because someone interfacing with your API only needs to discover the relevant URL once and then as long as your API doesn't change they don't have to care any more. Further even if you did write a fully HATEOAS supported REST API, the main benefit is supposed to be that clients don't need to hard code URLs and so it doesn't matter if you change the URLs. However you've no way of preventing API clients from not hard-coding the URLs and so if you ever do change the structure then you're going to have unhappy clients. Take the web for example, it's a (mostly) properly implemented REST API but link rot is still a major issue because everyone still relies on fixed URLs.
Then if links aren't that important, the simplicity of JSON wins out. Being able to represent both arrays and objects so naturally is hard to argue against. The entire spectrum of programming languages care fundamentally about arrays (lists) and objects (dictionaries/maps). The fact that you can't simply represent an array in XML or HTML is a major drawback.
Another problem against it, is that a large proportion of web developers are programming in JavaScript and then it's a no brainer to interop with JSON and you have to have major benefits to persuade your boss to use something else.