Monday, March 25, 2013

If APIs are well documented, do they need generated clients?

I was at Ed J's wedding, and a guest came up to me and said, "I started to read your new blog....".  Oh crap, looks like I need to keep going.  

So what have I been up to?  I did spend some time documenting and prototyping a few new API concepts that I've been kicking around.  I do have to say that the tooling from Mashape, is really nice.  I don't have any idea what the runtime is like, but for simply capturing a REST API and getting some pretty nice documentation. it does the job.  It also generates client libraries in different languages (Java, Python, Ruby, PHP, Object-C).  This is "slick", but I'm not sure how important client side libraries are going to be for REST.  In SOAP, the whole purpose of WSDL was to be able to build compatible clients.  This is because SOAP is much more complex.  Isn't the elegance of REST supposed to eliminate the need for client bindings?  Its just so simple, you can generate the client calls you need yourself?  

Like I said, I'm really trying to see the parallels between the evolution of SOAP and REST...and see if I can learn anything useful.  REST will probably just follow the typical hype cycle, but maybe we're all getting a little too smart (read: I'm getting old) for that.  Only time will tell.

1 comment:

  1. The big aim of having a REST call is to avoid having clients a dependency on your libraries..Yes documentation will certainly help but libraries may be an overkill.

    ReplyDelete