3 ms·
"I also didn’t mention the whole REST/RPC/Hypstermedia debate since I consider it being an implementation detail and a totally orthogonal discussion." with res
by AffableSpatula 14y ago
"I also didn’t mention the whole REST/RPC/Hypstermedia debate since I consider it being an implementation detail and a totally orthogonal discussion."
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.
- mattetti 14y agoI see your point, what I was trying to convey though, was that whatever style you decide to adopt, you still need to value communication, consistency, reliability and maintainability. > "The details of how you put that together in the backend are inconsequential to this challenge since they are hidden behind HTTP." That's is true, except that to integrate well with the "ecosystem of clients you don't control", you need a way to communicate with the people behind the clients. And that's what matters to me whatever technical solution you use.
- AffableSpatula 14y agothe interface you establish is the ultimate form of communication with the people behind the clients. You can't force people to read/obey documentation (no matter how pretty or up-to-date it is), but they are obliged (naturally) to follow the rules of your interface. 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).
- MatthewPhillips 14y agoAlso, if you follow REST closely your APIs should be self documenting.
- mattetti 14y agoI have yet to see a REST interface that self describes in details its incoming params and output. REST gives you discoverability which is different from documentation.
- jrochkind1 14y agoPlus, it's actually really HATEOS that gives you discoverability, not just any old REST. 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.
- mattetti 14y agoI fully agree, the point that I'm trying to make is that there is a step in between you offering an API and people using it. Explicitly defining your interface will make the transition easier for 3rd party developers.