There’re a number of excellent micro-frameworks to author RESTful APIs in Ruby. Let’s take a look at the newcomer, Poncho, from the Stripe team, brought up on the Grape mailing list. For those that don’t know me, I’m the maintainer of Grape and use it very heavily at Artsy. I’ll do my best not to be biased.
With Poncho you start by declaring resources that inherit from Poncho::Resource. A resource is a prescriptive way of declaring what parameters to expect and what results to render from the API. In many ways resources are similar to Grape’s entities, except that the latter are no longer part of Grape and you can use roar, rabl or any other framework to render results - you choose. Poncho resources include parameter validation, which makes sense. Personally, language matters, so I would not call values that can be assigned to the resource parameters, but maybe fields or attributes.
You then declare a Poncho::JSONMethod, which inherits from Poncho::Method, which is a piece of middleware. The former is equivalent to a Grape formatter, and the latter is equivalent to the Grape endpoint Rack middleware. You have to override the invoke method and implement your business logic.
How does all this come together?
Grape could easily support the Poncho syntax with a few lines of code. Internally it creates a Proc from the body of the block.
I think that Poncho is in the very early days of development and has made some choices that Grape already made a year or two ago and decided undo more recently. Poncho hasn’t dealt with more complicated problems like versioning or content-negotiation, yet. Once it does, poncho contributors will find that infrastructure begins to bloat and will likely split it the same way we split grape and grape-entity. My current view is that the API DSL layer should be providing functionality closer to the HTTP protocol and a separate entities-like library should deal with data representation. That’s because I have strong opinions that a modern API should be a Hypermedia one, but I would not want to impose this on anyone, which is incidentally a similar philosophy that lead to Webmachine (check out my earlier Grape vs. Webmachine post).
That said, none of the above is difficult to accomplish.
I would certainly have preferred if Stripe chose Grape as the API DSL and implemented their style of data presenters if they felt strongly about that. But we all want our own micro frameworks, don’t we?