Hacker News Reader

Comment by rajangdavis | Hacker News Reader

Pardon my ignorance, but what is wrong with a JSON response and how does this library solve that problem?

I don't think you're ignorant. To me, it is niave for anyone to think that HTML meets all needs for response data. Having to support everything that HTML can do relay limits the practicality. Similarly, HTML can't support every kind of response you might want to provide, and then you're forced into parsing or transforming the HTML. It's stupid.

You are missing the point of the article. I am not suggesting that people use HTML APIs in place of JSON APIs. I am suggesting that they should use something else for that:

It’s time to admit it: the REST-haters are right. REST does not make for a great raw data-level API architecture, and efforts like GraphQL and RPC-like architectures are likely to end up producing something more usable for complicated data needs.

Rather I am suggesting that the REST-ful architecture can be rescued from API use, using HATEOS and annotated HTML in web applications.

This article took a long time to write and, while I don't expect people to agree with me on the value of REST/HATEOS or the viability of intercooler as a web application library, I do think it is worth taking time to understand my argument.

The time you spent on this is much appreciated. Everyone is trying to get a handle on the best way to do web development.

I also appreciate people that either (1) buck the SPA/JS trend for the purpose of trying to make the web more accessible, or (2) develop APIs that are at least usable in theory by clients that don't limit accessibility.

However, when you rely on a combination of JS and HTML that isn't accessible and APIs that can't be used easily by non-browser clients, I don't care whether you are trying to adhere to Roy Fielding's vision or not, I can't go for that.

It reminds me a little of Tim Berners Lee pushing for https://en.wikipedia.org/wiki/Semantic_Web with dreams of https://en.wikipedia.org/wiki/SPARQL supporting databases and https://en.wikipedia.org/wiki/RDF_query_language defining everything. Really smart guy. Really neat idea of how things could have worked. But the real world is not like that, and it isn't filling the needs of today's web developers in a smart, fun, and practical way.

If we're going to "fix" web development, let's just start over.

How about defining data to view/feel/hear and APIs to use in a way that doesn't enforce the method that you use to interact with them? What if webpages were JSON instead, and that JSON could embed definitions of available services? What if all of the web was decentralized so we weren't reliant on anything except the device you used to host this JSON and its services and it was easily scalable across peers that decided to host it?

That's the sort of future I'd be in favor of.

I have returned RDF/N3 from my web services for years. And transformed that data into a Javascript graph of objects on the client with the library available at https://github.com/RubenVerborgh/N3.js.

It is very flexible. Each object has a unique identifier. That identifier is dereferencable as a URL. Each object has a type (because the Semantic Web is all about typing your data, and applying your code on data of a given type). The graph can be traversed in any way I want on the client.

Honestly, this makes things quite simple.

I like the idea behind the semantic web and if everyone had the bandwidth to commit resources to it, it would definitely add additional abilities to the web. But, in my experience, the time spent on adding RDF support wasn't worth the adoption or limited gains in site usage.

What are its usage metrics in your site(s)? Does it appear that there is significant growth in its adoption?

Facebook's has offered RDF for a while. I've not heard of its use outside of academic circles.

RDF has no adoption. JSON is the winner. Let's try to understand why: Because JSON.parse() is instantly available on the client. On the contrary, RDF.parse() (or more precisely N3.parse()) is available on the client only if you use that obscure library I mentionned above. Noone knows the library, so noone uses the N3.parse(). Ok. End of discussion.

Now my own feeling: RDF (and especially its N3 dialect) is the only description language I know of that serializes and deserializes graphs with no specific code, and has a good JS lib for client-side consumption.

JSON (or XML, or any other tree descrption language) requires extra effort whenever you use it to serialize/deserialize/traverse a graph structure. That is why i think they suck. And that's why I prefer RDF/N3.

I would suggest reading the article and the linked articles in it, and then thinking about it for a bit.

I do not mean this flippantly.

I wrote that question after reading the article, I am just not really understanding why an HTML response would be a better alternative to JSON. I thought the whole reason JSON was used for RESTful API's due to the client-server principal.

After rereading the article, if I understand what you are saying, the reason why the library was written was to address two failings with JSON based API's: They do not follow the HATEOAS requirement of REST and a JSON API may not have the same flexibility as raw SQL.

To be honest, I am still a little confused and not really understanding what problem is being solved by the library... I am sorry.

OK, let me try to summarize:

REST does not work well for JSON APIs

This is because HATEOAS for JSON APIs never worked out

JSON APIs will continue to move away from REST and towards RPC and SQL-like architectures

However, if you wish to adopt a REST-ful architecture for your web application (and I think it is a good one for many applications), there is a good way to do so: have your server return bits of HTML, which naturally allows for HATEOS, and use a library like intercooler.js to fully embrace the concept.

Does that clarify?

I did little research and now I understand why I was confused. JSON lacks hypermedia support which makes it violate HATEAOS (http://restcookbook.com/Mediatypes/json/ ); inherently, there can never be a RESTful, JSON API beca use it violates this principle. Everything I know about REST is wrong! Thanks for taking time to write out your response and this article, I was missing this one piece and couldn't wrap my head around it.

I'm not sure this is correct. Even the link provided does not exclude JSON as a media type. Just because there aren't (m)any examples of RESTful JSON API's doesn't mean there can't be.

My understanding is that as long as you standardize the way in which hypermedia is communicated through the API, it could be RESTful.

The REST paper desires to reuse existing doc types. If you create some linkable JSON, you've made a new type. So now everyone that wants to interact with your data has to first use your type. They will have to say Accepts:x-new-linky-json. Your type will probably be a bit different than someone else's linking JSON. So now we've got type explosion.

I don't advocate the creation of a new media type.

My take on REST is that for an API to be RESTful, the API definition should really be the definition of a hypermedia format. The format definition then informs the interpretation of a hypermedia response such that state transitions can be made by the client. If our encoding of a hypermedia response is a JSON document, the format definition should describe how we can interpret that response to perform some action.

If the service we provide is as general as a Web Page, then using a standardised format like HTML makes a huge amount of sense. If the service we provide is an API to some specific functionality, it seems reasonable to me that we can define the interpretation of some specific media type as a part of the specific hypermedia format that drives the interface.

Then again my interpretation of REST could be completely backwards and I would appreciate corrections.

You cannot interpret a media type. They have a definite meaning.JSON does not have a linking ability. To make it, you've created a new mime type.

REST is an interesting architecture. It can inform your decision. If you don't follow its prescriptions, you are not following REST. You are merely informed by it. That is fine. Don't confuse the two.

Reply on news.ycombinator.com