3 ms·

What syntax should one use to define link relationships in a RESTful service? Most of the examples I've seen extolling the virtues of HATEOAS use XML, specific

What syntax should one use to define link relationships in a RESTful service? Most of the examples I've seen extolling the virtues of HATEOAS use XML, specifically the <link uri="..." rel="..." /> element. That's great for a single media type (XML), but what about JSON, which is by far the dominant media type used in RESTful APIs? A google search for "hateoas json": https://www.google.com/#q=hateoas+json&fp=1 https://www.google.com/#q=hateoas+json&fp=1 reveals...a bunch of people asking how to format link relations in JSON, without a definitive answer that I can see. HATEOAS and discoverability are principles that sound great in high-level discussions but I have yet to see them implemented in a meaningful, helpful way. Anyhow, you seem quite knowledgable on the subject so perhaps you can enlighten me. Usually it's my own ignorance/obstinateness that's to blame rather than a flaw in the concepts themselves...

scott_w 15y ago
I would argue that you don't. JSON isn't a format for HATEOAS, for the reason you state. I'm leaning towards saying HTML 5, with some of the new semantic markup, though it's not perfect. You can use both, and simply use the Accept HTTP header to determine which format you want. It gives you both discoverability of HTML (with <a>), and data transfer that is easy to parse.
jalfresi 15y ago
I agree, I too have seen lots of discussions of how to format links in JSON. As you noted, JSON is not a hypermedia format per se, but if you use the Link HTTP header you can add hypermedia to non-hypermedia mediatypes. Here is a quick example: HTTP Response: HTTP/1.1 200 Ok ... Link: <http://example.com/some-resource>; rel="edit"; title="Edit some resource" Content-type: application/json {"prop":"val"} You should be able to see that the link header contains a target url, a relation and optional title. The Link header maps almost exactly to the HTML Link element. I agree, I havent seen a "true" RESTful service either, except for very simple examples. As others have noted, REST is quite a difficult architectural style to summarise in a few short pithy statements, which leads a lot to the confusion on implementation. I also think that the fact that the architectural style is defined by constraints, which traditionally flies in the face of all previous architectural styles I have seen, which emphasise features and what you CAN do. REST is about what you DONT do. Its these restrictions that combine to make something very powerful, flexible and scalable. Think chess: its a stupid game with a board limited in size, the pieces all move in complicated but specific ways. It cant possibly be an interesting and deep game with all these constraints! If you are interested in discussions on the subject, I recommend joining the rest-discuss mailing list on Yahoo Groups. Sure the conversation veers into hand-wavy, ivory tower territory, which can be forgiven seeing as the discussion group is for exactly this, but you get some very comprehensive and detailed explanations. Definitely search the archives because a lot of stuff has been answered in great detail before. Roy Fielding even pops on sometimes to correct a few points, and you dont get much more authoritative on the subject than that :)

scott_w 15y ago

I would argue that you don't. JSON isn't a format for HATEOAS, for the reason you state. I'm leaning towards saying HTML 5, with some of the new semantic markup, though it's not perfect. You can use both, and simply use the Accept HTTP header to determine which format you want. It gives you both discoverability of HTML (with <a>), and data transfer that is easy to parse.

jalfresi 15y ago

I agree, I too have seen lots of discussions of how to format links in JSON. As you noted, JSON is not a hypermedia format per se, but if you use the Link HTTP header you can add hypermedia to non-hypermedia mediatypes. Here is a quick example: HTTP Response: HTTP/1.1 200 Ok ... Link: <http://example.com/some-resource>; rel="edit"; title="Edit some resource" Content-type: application/json {"prop":"val"} You should be able to see that the link header contains a target url, a relation and optional title. The Link header maps almost exactly to the HTML Link element. I agree, I havent seen a "true" RESTful service either, except for very simple examples. As others have noted, REST is quite a difficult architectural style to summarise in a few short pithy statements, which leads a lot to the confusion on implementation. I also think that the fact that the architectural style is defined by constraints, which traditionally flies in the face of all previous architectural styles I have seen, which emphasise features and what you CAN do. REST is about what you DONT do. Its these restrictions that combine to make something very powerful, flexible and scalable. Think chess: its a stupid game with a board limited in size, the pieces all move in complicated but specific ways. It cant possibly be an interesting and deep game with all these constraints! If you are interested in discussions on the subject, I recommend joining the rest-discuss mailing list on Yahoo Groups. Sure the conversation veers into hand-wavy, ivory tower territory, which can be forgiven seeing as the discussion group is for exactly this, but you get some very comprehensive and detailed explanations. Definitely search the archives because a lot of stuff has been answered in great detail before. Roy Fielding even pops on sometimes to correct a few points, and you dont get much more authoritative on the subject than that :)