Dan Jemiolo posted today about his restdoc tool, which produces Gregorio Tables from comments in REST service implementations designed to be run in Project Zero. He also posted to the Project Zero forum, and included some screen shots of the output of his tool, here.
Here is what's cool about this:
I love it when I can keep artifact information like this with my source code; easy to keep in sync.
It's genuinely useful information.
I'm tired of the "we don't need no stinkin' tools" attitude of some of the RESTafarians. Baloney. I think we can certainly live without overengineered tools like WSDL, but having small tools can certainly help.
Now, for some rocks:
As I mentioned in a comment on Dan's blog, it would probably be useful to have this information available at runtime on the server; the server could actually validate what it's doing. And I'm not talking about the server reading it's restdoc information back in; I'm talking about the server having that information available to it, at runtime, obtained reflectively. The advantage is that you know the information is never stale. No more, "When was the last time I ran restdoc again?". In Java, you would presumably use annotations to do this.
While Joe's tables included a non-precise description of the HTTP content for the method / uri rows (eg, "Employee Format"), restdoc only includes the 'format' (eg, JSON). I'd prefer to see more precise typing, but to start with, something as vague as Joe's would be good.
That HTML table looks like it may be too wide to be viewed on an iPhone. The good news is, I don't have to worry about that problem.
Finally, not to knock Dan at all, but I really have to wonder what's going on if the best we can do is describe our services in human readable tables of text. Really? I mean, can't these multi-core, multi-gigahertz computers of ours really help out anymore than by rendering some HTML to a display that we read while hand-coding our HTTP invocations?
That just isn't right.
No comments:
Post a Comment