I 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.
Re:Rethinking web API development
by MatthewPhillips on Wednesday June 13, 2012 @03:32PM
(#4107950)
Also, if you follow REST closely your APIs should be self documenting.
I 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.
Re:Rethinking web API development
by jrochkind1 on Wednesday June 20, 2012 @09:47AM
(#4136918)
Plus, 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.
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).