REST API, why no HTML instead of JSON?

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">
    <a href="/people/12" id="12" class="com.graceland.elvis.Person">wife</a>
    <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