Rethinking web API development
matt.aimonetti.net
matt.aimonetti.net
I don't believe that Webmachine forces you into "a specific way of providing your data." It wants you to provide data in a format that both your service and the client are prepared to understand, again, that seams reasonable.
with respect to the author this article is well intentioned but it is (in my opinion) fundamentally misguided..
The choice of any of those styles will directly and deeply effect how your clients consume (i.e. couple) to your API.. and ultimately how you are able to evolve and maintain your application over time without heavily disrupting code written against your service.
Rails is perfectly adequate for exposing resources, rendering representations, and for publishing documentation - producing yet another framework that is entirely focused on API might help but in largely superficial ways. The challenge of good API design is in exposing it to the world so that it evokes the right behaviour from an ecosystem of clients you don't control the code for. The details of how you put the API and documentation together in the backend are inconsequential to this challenge since it is all hidden from clients behind HTTP.
It's also worth bearing in mind that the design you pick will directly affect how you document your API - documentation of RPC APIs are different from that of Rails-style CRUD-over-HTTP APIs, which in turn are different from that of REST APIs (or "hypermedia APIs" - redundant term, really).
But either way, I agree with you, while the theory is that if you do it 'right' one way or another it's self-documenting, I have yet to see an API which doesn't need good documentation to be usable.
Well, actually, that's a lie, I've seen at least one: The TinyURL "api". Which is obviously extremely simple.
In other words, I need it to work well with implementing an oauth provider functionality.
Also potentially one needs to come up with a way for an API consumer to be able to generate oauth credentials in a (hopefully) user friendly way.
Hence Id prefer full Rails environment with things like Devise and ActiveAdmin
Last year I worked with a very big and monolithic Rails app and all the time I was wondering about move it for services but it wasn't possible.
I'm almost convinced that we can write service layers with a very consistent API and use Rails to consume it as a client. The HTML interface should be only another client.
My experience might be different than yours, but very often my html views quickly end up needed more than 1 resource to render and now I need to fetch data just for the html templates. The same data set isn't needed when returning json or xml and the API end points exposed for data consumption are often quite different. That said, in some cases, I agree that your approach would work.
In the real world the HTML output is not like JSON or XML as you told.
It is used to show data to a human and most of the time it contains a lot of elements that are not related with the resource data even if it is not representing more than a resource in the same page.
The interaction with a human doesn't happen in the same way as with another system.
You can pretty easily share models and whatnot -- and then you have a nice clean place to define/override your DSL. I would have to do some playing to make sure this is valid, but that might be an approach to think about.
Granted, DSL is a lot easier to read, since it is using Ruby syntax instead of XML. Functionally, they are the same.
Or you use different meta-patterns, and you stop lying to yourself (and to everybody else). That's fine, regular web interactions work and work well and they have structural advantages. They just can't do MVC in any sensible manner.