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.