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

[RichardJordan]

Cheers for the links - watching this thread keenly right now while trying to figure out the best way to do this.

[dblock]

I hacked together a prototype gem for Roar w/ Grape, confirming that we don't need to do anything special anymore. It just uses Grape::Formatter::Json. You can use representers "normally" and just call to_json in your APIs from representers.

If anyone believes we can add useful features for better Roar support, the above can serve as a skeleton.

I'm going to close this request, since I don't think we should modify Grape entities to allow hypermedia - gems like Roar do a great job at it. Please speak up if you think I'm wrong.

[dblock]

Also added this to the README.

---

Hypermedia and other RESTful Representations

Although Grape ships with its own entity support, it's also possible to use it with other frameworks and renderers.

Hypermedia

Use Roar. Include Roar::Representer::JSON in your models or call to_json explicitly on representers in your API.

Rabl

Rabl is supported via the grape-rabl gem.

[steveklabnik]

Can we get an AMS shout out too, if you're covering RABL? Trying to get the
word out about it too.

On Monday, December 24, 2012, Daniel Doubrovkine (dB.) wrote:

Also added this to the README.

Hypermedia and other RESTful Representations

Although Grape ships with its own entity support, it's also possible to
use it with other frameworks and renderers.
Hypermedia

Use Roar https://github.com/apotonick/roar. Include
Roar::Representer::JSON in your models or call to_json explicitly on
representers in your API.
Rabl

Rabl https://github.com/nesquena/rabl is supported via the grape-rablhttps://github.com/LTe/grape-rablgem.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/270#issuecomment-11665537.

[dblock]

Totally, but I didn't get a chance to make it work with Grape yet. Want to do a demo and PR a link? If you need a custom formatter, you can pretty much clone my gem.

[steveklabnik]

I will submit a PR. Least I can do as its maintainer. :) just wanted to ask
before I did so.

On Monday, December 24, 2012, Daniel Doubrovkine (dB.) wrote:

Totally, but I didn't get a chance to make it work with Grape yet. Want to
do a demo and PR a link? If you need a custom formatter, you can pretty
much clone my gem.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/270#issuecomment-11666599.

[benshaw]

Is it possible to get an example or how to get roar and grape working together ?

[dblock]

There's actually nothing to do for Roar in Grape. I did a formatter in https://github.com/dblock/grape-roar, but that's unnecessary. Once you've setup your representers, you can just do as_json explicitly or simply return the object from the API and Grape's json formatter will take care of calling it.