4 ms·
What about the documentation angle? SOAP supporters claim that WSDL removes the need for custom-written documentation if combined with something like javadoc. R
by c1sc0 19y ago
What about the documentation angle? SOAP supporters claim that WSDL removes the need for custom-written documentation if combined with something like javadoc. REST inherently needs more documentation which makes things harder to maintain. Or so they claim ;-)
Anyone know a nice way to expose a webservice as SOAP/REST/XML-RPC & write the documentation automatically?
- wastedbrains 19y agoAs a coder when ever working with API's code examples of how to call and actually use the API's was worth a lot more to me than a ton of documentation. The WSDL along with JAVA doc does give some good information about the available calls, but I think having a few client examples in a couple langauages would probably benefit more users.
- c1sc0 19y agoI think one of the dirty little secrets of succesful api's is not in the API itself but in the example code / implementation libraries provided. Facebook had a great php lib initially & I see the ClickPass guys are providing lots of libraries on top of their API. Anyone else think just providing an API is not enough these days?
- johnm 19y agoBah! The only thing that e.g. WSDL brings is that the "contract" for the service can be baked into the legal contract between partnering organizations. For big paranoid companies where people need a lot of CYA, that can be a big point. Good RESTful approaches are actually self-documenting. As the example from my recent talk on REST at SD West shows, it's really easy to support human discoverable (i.e., well documented) RESTful solutions. In my example, hitting the root resource returns a page (in html or text) that shows how to interact with the resource with actual examples. That's way better then some horribly verbose WSDL that somebody is going to have to look up.
- andrewf 19y agoIf someone's writing a client in an IDE, WSDL gets them code completion.
- johnm 19y ago<insert snide comment on IDEs vs. Emacs/vi /> More seriously, another problem with the SOAP approach is that a lot of the toolchain'ish malarky around it hides reality from the developers and so they tend to create even worse abominations.