It seems that most bioinformatics web services use SOAP, and the extent of their documentation is the accompanying WSDL file - not very helpful for anyone who wants to use them outside a workflow-type tool like Taverna, and even then often not descriptive enough to know what should go in each field.
I've been documenting various APIs on HubLog as I come across them, mostly with sample PHP code, but it's getting a bit unwieldy. It would be good to have a database of bioinformatics APIs that anyone can edit and attach sample code in various languages for performing various functions. Is Nodalpoint a good place for this, or could there be somewhere better suited?
Comments
api wiki on nodalpoint
I suppose the nodalpoint wiki would a possible place to do this, we talked about doing something like this before....
On a related note, Franck Tanoh has been creating a list of (mostly WSDL) style bioinformatics web services and as Alf says, they are typically low on documentation, with a few exceptions like FUGE. There is always http://www.google.com/search?q=filetype:wsdl and the bioinformatics links directory as a starting point to populate such a wiki.
Feta
It looks like myGrid's Feta project is along the same lines - are there any plans to make the Feta database searchable and annotatable (by anyone) using a web browser?
Searchable, annotatable database of services: Feta?
There's three options for a searchable, annotatable database of services. What we have with Feta now, what Feta will become and what other projects are doing.
1. What we have with Feta today: Feta annotations are available programmatically via a Web Service interface, see Feta WSDL or you can browse the raw XML if you have the stomach for it. In the near future, there may be a SPARQL endpoint you can query too. As it stands, Feta is OK, but could be a lot better.
2. What Feta will become Feta is far from perfect and we hope to improve it in various ways. The WS4LS-Catalogue project led by Carole Goble here in Manchester and helped by Rodrigo Lopez at the EBI starts in February 2008 to build a better registry of Web services for the life sciences community. You can ask them for more details if you are interested.
3. Other projects If the current or future version of Feta doesn't do what you want, you can use BioMOBY. They've had a searchable annotatable database of services for a while now, one of their strengths is their PERL API which lets you register new services using terms from an extendable RDF ontology.
See Feta: A light-weight architecture for user oriented semantic service discovery by Phil Lord et al
php.net
Ideally what I'd like to see is something like the function documentation on php.net (eg simplexml): each service would have its own page, with an auto-generated outline of the service (from the WSDL file) and a block of "official" documentation and examples, then other people would be free to leave their own comments, clarifications and sample code snippets below.
simple xml
For REST style web services, WADL does the same kind of thing to simplexml at php.net, as far as I can see.
For SOAP+WSDL style services, it is currently much harder to create simple documentation, because as Tim puts it the WS-* stack is bloated, opaque, and insanely complex. I think it’s going to be hard to understand, hard to implement, hard to interoperate, and hard to secure.
Feta - controlled ontology for annotating web services
It seems to me that the whole point of Feta is to have a controlled ontology for annotating the input / output of the web services, so you can automatically plug things together in a workflow (Semantic web services). That's where the real effort saver comes from, because even if you have the inputs / outputs well documented, still you need to spend time figuring out the which ports you should connect between two web service components in a workflow. And that becomes hairy in a flow with many-many components !