Question about Percolator Media Type

[zdne]

Is there any documentation for the media type used by Percolator? To me it vaguely resembles HAL. Would you care to elaborate why not use an existing media type instead (e.g. those mentioned in kevinswiber/siren#15)?

Thank you.

[cainus]

I don't really have docs on the media-type yet. I started a first draft here: http://caines.ca/blog/programming/hyperjson-a-first-draft/ . The original impetus was discussed here: http://caines.ca/blog/programming/hyperjson/ but it's obviously evolved since both of these (in both power and simplicity). I've been meaning to write up a media-type description soon though; it's been in use by a number of people for over a year now, so it's solidified enough now that I should have docs.

I talked with Mike Kelly a bit about HAL and decided it didn't meet one of my primary requirements: I wanted links to also specify how the API can be written to (and not just for GETs like links usually are used). In that discussion at the kevinswiber/siren#15 , Mike explains that HAL purposely doesn't have "form" support, which is probably what he would agree would be equivalent to hyperjson's "links" that also support POST/PUT/DELETE.

I think it's fair to say that it's controversial about whether or not those types of links are useful in m2m scenarios, but I've personally found them to be useful in a lot of scenarios that are more user-interactive. One of the most interesting so far (IMO) is the browser in percolator. Scroll down to the screenshots here: http://caines.ca/blog/programming/so-i-wrote-a-json-api-framework-and-the-framework-was-the-least-interesting-part/ to see what I mean. It's a generalized way to surf and use any API written with the hyperjson mediatype.

Let me know if any of that does make sense, or if you have any other questions. Thanks for the interest!

[zdne]

Gregg this is very helpful answer! I have read through it all. Thank you!

I really like your effort and your opinionated approach in Percolator.js even more! I am really getting the impression that while the hypermedia situation on backends, frameworks and APIs is getting better, literally from day to day, it is the client side where we still have to break it to "win the war". Maybe the tools like hyperjson-browser could be used as a demonstration but I believe it is the actual clients frameworks that will play the key role.

[cainus]

Yeah you couldn't be more right. The way clients are built today reminds me of the early days when people used to parse XML APIs with regular expressions. I think the next gen clients won't have to piece together their own urls, and urls will be used opaquely (with a few exceptions where uri-templates make sense). We should be able to get rid of the typical "unique id" in every representation and instead just use uris.

And really that's just the beginning I think. There will be a whole bunch of new capabilities that organically emerge as we let clients rely more on the representations to determine their next moves.

I have a few ideas for more fully featured generic clients, but I haven't had a chance to tackle that problem yet. I saw a demo by Jon Moore somewhere that does much more.

I'd love to hear any ideas you might have as well...

[toddb]

Hi folks, can I add my cents in here echoing general agreement. Gregg, I just relooked at your hyperjson and what strikes me is that you don't pass around a type. Could you explain to me your decision? (obviously, I do).

Like earlier comments, I keep wondering about why we aren't seeing client libraries to make life easier. I keep coming back to the hegemonic position of RPC-style client/server design. I personally, I tended toward a pragmatic style of using text/html to specify my payload contracts where having to fill in the details. In other words, if you need to construct an object to send back, I'll give you a form. Fill it out and post it back. If you are updating then give me back the original representation (usually json) with the changes. Such a simple design leads us to simple helper libraries for followings links, but that's about all. If you are interested in my research code it can be found here and more specifically this link relation helper

[cainus]

I've actually kind of always thought of the link format in hyper+json as having an optional type property that implicitly defaults to application/json in the case of PUT/POST and is made redundant (and therefore unnecessary) in the case of GET by Content-Type and Accept headers. So in short, I like the idea, but it covers corner cases that I haven't got around to. This talk sure is making me feel like I should have had an updated description of hyper+json before now. :) I'll hammer something more formal out this weekend. Percolator already lets you add whatever attributes you want, so nothing is blocking you from putting type on all links today.

Your links look a lot like mine too, so that's very cool. :) One slight difference I think is that I use a json object instead of an array, and I use the rel as the key. This makes it so that finding specific links is a direct access lookup for clients, eg: representation._links.parent. It's a little thing, but a little thing that makes it more likely that people will access the links from the representation rather than hard-code them into clients, as they seem to always want to do.

Of course the biggest difference is that I don't see you specifying how state-changing methods (PUT/POST/DELETE) should work. Maybe I missed that or maybe it's on purpose. I've had value from describing those capabilities as well though.

What sorts of features are you looking for in client libraries? I have ideas about caching, rel-following, book-marking, etc, but I'm interested to hear what other people imagining. I agree that the client side is definitely the more interesting space now, because I keep finding new ways to exploit hypermedia that I hadn't previously.

[cainus]

Alright... I wrote something up really quickly this morning: https://github.com/cainus/hyper-json-spec . If you guys have any feedback, I'm all ears.