4 ms·
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
by daliwali 10y ago
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/ http://json-ld.org/
[2]: http://json-ld.org/spec/latest/json-ld-api-best-practices/ http://json-ld.org/spec/latest/json-ld-api-best-practices/
[3]: http://micro-api.org/ http://micro-api.org/
[4]: http://www.markus-lanthaler.com/hydra/ http://www.markus-lanthaler.com/hydra/
- BigChiefSmokem 10y agoThis 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.
- deleted 10y ago[deleted]
- daliwali 10y ago>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.
- deleted 10y ago[deleted]
- edblarney 10y agoIt's heavy 'REST' oriented. A Java guideline for API's would like completely different.
- cdcarter 10y agoThe guide actually explicitly says it is focused on gRPC.
- zeveb 10y agoHow 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=}
- daliwali 10y agoThe 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.
- einrealist 10y agoI'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".
- tincholio 10y agoEver heard of LISP, or S-expressions?
- tom_b 10y agoI 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 . . .
- mcherm 10y ago> 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 http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
- daliwali 10y agoI 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-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...