I’ve been working on a WSDL 2.0 description of the Flickr API.  My first attempt is here. Follows are some thoughts on this process:

Why a WSDL?

There are two reasons motivating me to want a WSDL for Flickr.  First of all, the WSDL 2.0 WG needs to prove that the HTTP binding has utility in describing existing REST or POX services.  Flickr seemed like a good stress test.  Secondly, once I have a WSDL I can automatically generate stubs for dynamic languages (a part of the Web Services Mashup Server I’m working on).  That should (ideally) simplify the interactions with Flickr and I wanted to see how much progress could be made.

Google failed to uncover any Flickr WSDL (1.1), just a number of people bemoaning the lack of one.  So I had to set forth on my own.

Flickr SOAP and WSDL

A quick look at the Flickr SOAP interface (the one you’d expect to be reasonably describable by WSDL 1.1) shows that they use a wrapped technique that make it very difficult to write a clean XML Schema, and therefore WSDL, for the service.  Traditionally, each operation in a SOAP-based Web service (e.g. flickr.photos.search) accepts and returns blocks of XML, which is described by XML Schema.  Since XML Schema associates an element name with a single structure, different operations, at least those requiring different structure, choose different names for the XML payload.  Flickr however wraps the parameters which comprise each request in a single element:

<x:FlickrRequest xmlns:x="urn:flickr">
  <method>flickr.test.echo</method>
  <someparameter>value</someparameter>
</x:FlickrRequest>

Note that the name of the operation (flickr.test.echo) is buried inside the payload.  There is a co-constraint between the value of the <method> element and the other parameters in the body.  This co-constraint is not expressible in XML Schema, which associates the <x:FlickrRequest> element with a single structural type.  Responses are similarly wrapped in an <x:FlickrResponse> element.  Because each operation returns the same element, a straightforward WSDL can’t do much better than an xs:anyType when describing the messages.

Note that WSDL 1.1 had a hack that helped here - you could describe the type of the body, rather than pointing to an element declaration that represented it.  WSDL 2.0 removed this hack in the name of simplification - a good choice in general but Flickr really could use the hack.

Flickr SOAP and HTTP

The WSDL 2.0 HTTP Binding actually does a better job than the SOAP binding here.  Since the XML structure of the operation is mapped into parameters, a wrapper element declaration doesn’t appear on the wire, so one can make up a different element name (as I’ve done) for each operation.  The return types from the Flickr REST API are still a single type of element (even worse than the SOAP case since the same wrapper element appears around both successful responses and faults).  But formulating the request has the highest value-add from the stub-generation point of view.

Flickr Authentication

The Flickr authentication scheme seems likely to make the WSDL description less than useful.  Most of the operations (the "write" ones) require authentication, yet the mechanism for authentication and signing seems pretty unique to Flickr - and therefore is likely to interact badly with general-purpose tooling.  I’ll have to play with this more to see whether this will require so much hand-coding that having WSDL at all is irrelevant.

Random Thoughts

One thing that an official WSDL would force, is a little more rigor in versioning the Flickr API.  It appears from the mailing list that changes to the API happen occasionally, but I wasn’t able to find a clean identifier for the various versions of the API as it evolves.  Having metadata that could be associated with stable (dated) identifiers would help customers of the API have a consistent experience over time.

An interesting anomaly is that the SOAP API and the REST API really must be considered different APIs at this point from the WSDL perspective.  That is, the XML Payload you get back is different depending on whether you access it through the SOAP or REST API.  WSDL separates the payload structure from how the XML is transmitted on the wire, but would require some XML transformation capability in the bindings to expose a single abstract set of messages through alternate transports (like SOAP vs. raw HTTP).  That means, if you change the way you get the payload delivered to you, you also have to change the way you access the contents of the payload - a Flickr poorly separates these concerns IMO (predicated on the definition of "payload" being the child of the <soap:Body> or the HTTP envelope).

Also I need to think a little more on whether Flickr’s design is optimal as a REST API and just hard to describe within the constraints of WSDL and XML Schema, or whether it’s generally suboptimal and that’s what is making it hard to describe.  Right now it seems neutral to me - the API would be just as easy to use if it were designed in a little more WSDL-friendly way but I can’t yet see compelling rationale for changing it other than to make it more WSDL-friendly.

Anyway, please send me any feedback you have on the WSDL.