REST API, why no HTML instead of JSON?
Asked Answered
N

5

9

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?

Nigritude answered 12/2, 2015 at 15:1 Comment(3)
The HTML spec is not suitable for representing data really. XML however is flexible enough.Hirohito
It is impractical. HTML comes with tags which primary goal is to structure content on the page which is to be viewed by humans. When using REST, the intended consumer is another application. And programs do not care if the headline is big, small, if there is a paragraph, etc. In a nutshell, you need basically what (lets say) JSON provides: simply-structurable data format with objects and arrays. With this, you can make everything you want.Elamitic
@Elamitic XML doesn't provide arrays either but people still use XML for REST APIsGravity
Y
9

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!

Yeryerevan answered 12/2, 2015 at 15:44 Comment(2)
If more time would be spent making HTML suitable for data representations, would XML be obsolete? Also, what is your opinion on JSON-LD?Nigritude
There's no need. HTML is already suitable. Far more suitable than JSON. Especially since with HTML 5 you can now embed data. The whole point of XML is that it is 'extensible' so it will never go away, it will only get more 'extended'. HTML is very tightly controlled by the W3C. All HTML clients will understand anchors and img tags etc. This makes it very useful. The problem with JSON is that nobody is really governing it properly. Sure you can extend it (LD etc.) but none of the extensions are universally supported in the way that HTML is.Yeryerevan
H
6

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 ?
Hydrotaxis answered 12/2, 2015 at 15:5 Comment(2)
Agreed, you need the flexibility of something that will serialize and deserialize across many platforms, presentations, code bases.Jetliner
It can be well formed (XHTML), the markup doesn't need to be any more verbose than XML. The rest of your arguments against seem to be just JSON vs XML. If we assume that XML isn't a terrible idea for a REST API (lots of people have done this) nothing here says why it would be terrible to use a strict subset of XHTML (similar to how JSON is a strict subset of JavaScript) instead of XML. Especially if HATEOAS is important to your API then XHTML seems a reasonable choice.Gravity
L
6

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

Lemuellemuela answered 15/2, 2015 at 13:19 Comment(1)
Not only you. :-) Compare http:/start.spring.io with CURL and browserDerbent
C
2

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.

Cusped answered 13/2, 2015 at 14:10 Comment(0)
G
1

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>
  <a href="../movies/avatar-theatrical-trailer.html" itemprop="trailer">Trailer</a>
</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.

Gravity answered 14/11, 2018 at 9:23 Comment(1)
I think this is one of the better answers here. However, I do wonder if "The fact that you can't simply represent an array in XML or HTML is a major drawback." might be wrong. In HTML couldn't <ul> be used for an array/list, and <dl> be used for a dictionary/map?Writeoff

© 2022 - 2024 — McMap. All rights reserved.