Re: Service discovery formats

[Sam Ruby <rubys@xxxxxxxxxxxxxxxx>]

Dare Obasanjo wrote:
> --- Danny Ayers <danny666@xxxxxxxxxxx> wrote:
>
> > >  "wsdl.exe http://www.blogengine.com/API.wsdl";
> > > and *poof* they have a .NET client with methods
> >
> > like
> >
> > >  createPost(String author, String entry, ...)
> >
> > That could be rather a big plus for encouraging
> > adoption!
>
> It isn't as straightforward as you think. 
>
> This approach is too tightly bound. It means the
> client has to be compiled against a particular WSDL
> which doesn't make sense when each blog server may
> support different aspects of the Atom API or have
> extension to the API. 

A better approach is one where the object is a document literal, with 
the approriate use of xsd:any.  Then, there can be multiple WSDLs which 
share a common core.  Things that are expected will be mapped cleanly. 
Things that are not, will be retained.

The resulting C# client logic will look more like the following:

   entry post = new entry();
   post.issued = new DateTime();
   post.content = "Hello World!";

   AtomAPI api = new AtomAPI();
   api.POST(entry);

The advantage of such an approach is that new fields can be added 
without requiring any code changes.  Authentication headers can be 
pretty much handled the same way, with something like the following 
inserted immediately before the POST:

  auth credentials = new auth();
  credentitials.user = "kpako";
  api.auth = credentials;

Open invitation: If somebody can prototype an implementation that looks 
roughly as follows: 
http://www.intertwingly.net/wiki/pie/BloggerProposals, and put up a 
public endpoint for me to test against, I'll create a WSDL and both a 
Java and C# implementation that uses the WSDL and a SOAP stack, as well 
as a Perl and Python implementation that don't use anything more than an 
XML parser.

This being said, my hope is that the BloggerProposal is evolved away 
from a custom set of headers and passing the password in the clear.  I 
would prefer something that was based on a secure digest or encryption 
and a documented standard.

> I've informally discussed with some of the XML Web
> Services folks about how to handle this introspection
> dynamically using the current .NET Framework [since
> I'll have to implement something like this in RSS
> Bandit eventually] and they've given me the impression
> that it is possible. Which is good since it means that
> a SOAP-based API will be able to be discovered
> dynamically without the client author having to futz
> around with XML if they don't want to while XML
> junkies like me can if they want to (at least for
> developers using the .NET Framework). 

+1

> I believe this dynamic discovery won't be necessary if
> the discovery process is structured differently (E.g.
> API functions are clustered together in a particular
> namespace and all functions in that namespace are
> mandatory). However I'm a novice when it comes to XML
> Web Services and acknowledge that this is just
> educated guesswork.  

Part of the issue is the number of URI's that will need to be dedicated 
to any given resource.  In RPC based systems, this typically is one per 
system.  The direction the AtomAPI is currently heading is for this to 
be one per service per resource.  My intuition is that the right place 
is someplace in the middle.

- Sam Ruby