Comment by daliwali | Hacker News Reader

Comment by daliwali | Hacker News Reader

What they describe is not REST. Nowhere in this document mentions hyperlinks, a strict requirement of the REST architectural style.

The best analogy would be a simple web page, which usually contains hyperlinks that a client can follow to discover new information. Unfortunately, web developers' understanding of REST ends with HTML, and they re-invent the wheel, badly, every time they create an ad hoc JSON-over-HTTP service.

There is a standardized solution for machine-to-machine REST: JSON-LD [1], with best practices[2] to follow, and even some formalized specs[3][4]. To Google's credit, they are now parsing JSON-LD in search results, which is much nicer to read and write than the various HTML-based micro-data formats.

On a related note, REST has nothing to do with pretty URLs, naming conventions, or even HTTP verbs. That is to say, it is independent of the HTTP protocol, but maps quite naturally to it.

[1]: http://json-ld.org/

[2]: http://json-ld.org/spec/latest/json-ld-api-best-practices/

[3]: http://micro-api.org/

[4]: http://www.markus-lanthaler.com/hydra/

> What they describe is not REST. [...] a strict requirement of the REST architectural style. [...]

You have a word "REST" for which you are apparently granted access to Plato's "true" definitions, which enables you to tell me that REST requires hyperlinks, but not naming conventions or HTTP verbs.

I reject your definition.

Go ahead and use that word "REST" however you like. I will continue using it to describe what you consider to be "ad hoc JSON-over-HTTP services".

Sure, I've read Fielding's dissertation.[1] I think stateless, cacheable, layered systems are a great idea. I think "code on demand" is (usually) a stupid one... even if it does turn out to work surprisingly well for web browsers. But none of those matter.

I work with people who build "ad hoc JSON-over-HTTP services". They spend hundreds of millions of dollars building ad hoc JSON-over-HTTP services. They call them "REST" services.

I have to talk to these people, so I call them "REST" services too. Because I'd rather build something useful than spend time telling people that they're using a word "wrong", when the only real meaning of a word is whatever it will bring to mind in the person you are communicating with.

[1]: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

I am not the authority on what REST is. That would be Roy Fielding, who has explicitly stated that hypermedia is a requirement[1]. So go ahead and tell Mr. Fielding that his definition of REST is incorrect.

I am well aware that REST no longer means what it originally described, which is why I think it should go by another term that is not burdened by being a marketing buzzword.

[1]: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

Don't worry, the term HATEOAS won't become trendy any time soon.

It's far too late for that. REST as you describe it is not commonly known as REST. People refer to it as HATEOAS or "real REST" or "hypermedia REST". Just saying REST without qualification refers to resource-oriented json based apis.

"Hypermedia APIs" seems to be the up-and-coming term.

> So go ahead and tell Mr. Fielding that his definition of REST is incorrect.

Not "incorrect", but I'd be happy to tell him that his term has been co-opted by the programming masses to means something vaguely related to the original meaning but less precise. I suspect Mr. Fielding already knows that.

> I am well aware that REST no longer means what it originally described, which is why I think it should go by another term that is not burdened by being a marketing buzzword.

I agree there. I think changing how the masses use the term is a lost cause. (Consider the incredibly hard-fought battle to reclaim the original definition of "hacker", which after decades did succeed in establishing it as a secondary definition. That's the most successful case I've ever seen.) So I think ryeguy has it right: call Fielding's definition "HATEOAS" "real REST" or "hypermedia REST" or something.

Wow, it seems linguistic prescriptivism has a stronger foothold in engineering domains. Probably fewer social class issues.

Well you sure confused the heck outta me.

---

It is really so hard to say "HTTP" instead of "REST"? "Regardless" instead of "irregardless"?

This is an API guideline, not a strict REST one. Also it has become very clear to me everyone has a different interpretation of what REST can or should be. We all are quick to forget that the actual acronym stands for "representational state transfer" which is an abstract concept and therefore can be implemented in many, many different ways.

>it has become very clear to me everyone has a different interpretation of what REST can or should be

This is very true, the term has been abused so much that it has no relation to its original meaning.

We can loosely define REST by one of its key qualities: hypermedia, that is a lot easier to say than HATEOAS. By focusing on this distinction, it rules out 99% of APIs in the wild.

On top of that, hypermedia media types and linked data are important for an API to be self-documenting, so there is a rather high bar for developers to implement.

It's heavy 'REST' oriented.

A Java guideline for API's would like completely different.

The guide actually explicitly says it is focused on gRPC.

I personally like collection+json as a response type for REST. I will say that my own efforts at using a hypermedia-containing response type for a REST api shared across several teams have been mostly wasted effort. Consumers of the api treat the responses as plain-old JSON which somewhat kills the advantages of having a proper REST response in the first place . . .

How is:

    {
      "@context": "http://json-ld.org/contexts/person.jsonld",
      "@id": "http://dbpedia.org/resource/John_Lennon",
      "name": "John Lennon",
      "born": "1940-10-09",
      "spouse": "http://dbpedia.org/resource/Cynthia_Lennon"
    }

Better than:

    (http://json-ld.org/contexts/person
     (id http://dbpedia.org/resource/John_Lennon)
     (name "John Lennon")
     (born 1940-10-09)
     (spouse http://dbpedia.org/resource/Cynthia_Lennon))

Note that the latter specifies a single canonical representation[1], which can be hashed and used for comparison, while the former does not (unless one specifies e.g. alphabetic ordering of properties). The latter format may also has a standard specification for transmission e.g. as a URL parameter[2].

And it's obviously a student-level exercise to write a validator, spec or grammar for the latter format, while the former is rather more open-ended.

Friends don't let friends JSON.

[1] Which HN sadly turns into a linked mess — Base64-decode the transport representation[2] if you'd like to see the canonical representation.

[2] {KDM0Omh0dHA6Ly9qc29uLWxkLm9yZy9jb250ZXh0cy9wZXJzb24oMjppZDM5Omh0dHA6Ly9kYnBl ZGlhLm9yZy9yZXNvdXJjZS9Kb2huX0xlbm5vbikoNDpuYW1lMTE6Sm9obiBMZW5ub24pKDQ6Ym9y bjEwOjE5NDAtMTAtMDkpKDY6c3BvdXNlNDI6aHR0cDovL2RicGVkaWEub3JnL3Jlc291cmNlL0N5 bnRoaWFfTGVubm9uKSk=}

The answer to that is really simple: JSON is a widely supported standard in many platforms and languages. Whatever the latter is, is not.

What's better than writing a parser for the latter format, is not having to write anything and just using a library, which exists in practically every language for JSON.

I'd argue, choose whatever format is best for your case. If its easy, chose a binary format for small footprint and a human readable format. But chose formats that are semantic and are able to drive the client. That's what the "R"epresentation is all about in "REST".

Ever heard of LISP, or S-expressions?

Of course, I even write some hobby projects in Common Lisp.

There are data interchange formats that use S-Expressions, namely EDN[1]. But JSON remains the most popular format for its widespread support, and its few data types map to most languages.

[1]: https://github.com/edn-format/edn

Reply on news.ycombinator.com