Hypermedia support?

[mattiassvedhem]

Is hypermedia support anything you've been thinking about adding so we can implement HATEOAS apis using grape in a simple way?

[dblock]

Nobody has worked on this. What does it take?

[mattiassvedhem]

I guess making Grape::Entity compatible with Hypermedia types like Hal and Collection+JSON would be a good start, and also the ability to create your own hypermedia types and plug them in somehow.

Maybe Roar could be used or looked at, they use representers as opposed to entities where they provide a links method. I guess that's a good start.

Also Designing Hypermedia APIs by @steveklabnik is a good resource. To my understanding the main idea is that the responses should act as a representation of the current state of the application and to provide available transitions for the client to act on. This semantics is described using Hypermedia types.

I believe Rails-api and Active Model Serializers is on the path for better Hypermedia support, atleast Steve uses active_model_serializers as an example, so maybe the concepts there could also be derived.

[steveklabnik]

You've got your head on straight, Mattias.

[dnd]

I was messing around last night, and started building some simple support for using Roar representers with #present. It was actually fairly simple, and allows you to still use Entities. It does depend on my currenly sort of hackish pull request #273. It allows you to extend either with either single representer, or an array of them.

If there's interest I can see about getting some specs written and package it up into a pull request. Though if there's going to be talk of supporting multiple representation frameworks, a little more design may be required so it doesn't get ugly.

[dblock]

I think any improvement towards multiple presentation frameworks will be more than welcome!

[steveklabnik]

Also, it would seem that HAL has been picking up a lot of steam lately, so if you're going to pick a format to emit by default, that should be it.

[dnd]

I would agree that HAL seems to be the one starting to take favor. I'm not familiar enough with Grape's development to know if that is a design goal.

The work that I'm planning would allow for either Grape's entities, or Roar representers. Though if we take it out further then I guess maybe ActiveModel serializers too. I think in any of those cases it's still up to the developer at the end of the chain to implement HAL, or whatever their flavor of output is.

If you're just referring to the default output by Grape's entity classes, then ignore this.

[dblock]

I can comment on Grape's design goals: we want it to be awesome and practical and community developed. So think of what you need and how to make it generic enough for everybody else :)

[dblock]

Wanted to add my increasing interest in this. I was talking to @macreery last night and this morning my clear head tells me that we've been doing API JSON representations all wrong and that Hypermedia is the way to go. I'll look into #273 today and plan to give Roar a try.

[mattiassvedhem]

Awesome @dblock, keep us posted!

[dnd]

If we want to remove the serializable_hash call completely then I can submit that pull request which will fix that problem, and then I can submit my changes that I have made to get Roar working with #present.

[dblock]

#282

[dblock]

I've made a few changes to the way formatters are defined and declared and made a pull request into grape-rabl to demonstrate this (ruby-grape/grape-rabl#6). You can now do this:

formatter :json, Grape::Formatter::Rabl

In the same vein it should now be possible to build a clean formatter for Roar, although I am not sure if we even need to given that you serialize a representer with to_json.

[dblock]

I guess the above is my question to @dnd - does this now work out of the box or should we build something more pretty?

[dblock]

Folks on this thread will be interested in some Russian doll stashing and bashing going on around Hypermedia w/ @dhh.

http://37signals.com/svn/posts/3373-getting-hyper-about-hypermedia-apis
http://blog.stateless.co/post/38378679843/hypermedia-apis-on-rails-why-dhh-should-give-a-fk