Yiyi Sun - Programming Blog

Service without description is a pain

June 8th, 2007

Too many debates are there about SOAP vs. REST, contract first vs. code first.

But here is my real life experience during developing WB Editor when it needs to connect web services through those famous RESTful style APIs.

First, the API documents usually have no schema definitions other than request and response XML examples.  Examples are good for human to read.  But after reading, where is the code that I can work with? I have to write code to parse those XML! - This is a pain. If there was schema, machine could generate client code stubs automatically. The nice “Add web reference” way.

Second, maybe the web service providers realized the issue mentioned above. Usually there are client libraries are also available, such as libraries for Java, for .NET, for PHP, for Python and for Javascript …. If using libraries, what is the differece between them to those C libraries ages ago? As long as the the library black box can talk to the server no needs to bother whether underneath it is HTTP, whether it is XML or binary.

I cannot imagine if in my company, when I publishing tones of web services to other departments or clients, I have to also deliver client libraries, for Java, for .NET ….

Tags: WB Editor, SOAP, REST, API, schema, Add web reference, web services

Entry Filed under: Links, Programming, WB Editor, blog