Yardi Store Developer eXchange

The web services in Store are all based on Microsoft’s WCF technology instead of the older ASMX model. While this has been a huge boost in flexibility for Store, it has led to some confusion for some of our clients. In this article, I’ll attempt to explain the differences between the two and the reason why Store 4 is built the way it is. (This may get a little technical, so hang on!) Let’s start at the beginning:

In Store 3.1, the web services were written using ASMX. That allowed us to easily expose all kinds of internal datatypes as XML – and since many of our services returned tables of data, it seemed like a logical solution to simply return .NET DataSet objects to our clients. However, since a .NET DataSet is only defined at runtime, the WSDL schema definitions for those tables don’t know what they will look like. As a result, the WSDL file uses a simple tag to represent the table: <xml:any> This tag is basically the XML equivalent of “Object” or “Var”. It is type-less. It means that when a client calls this service, they will receive a blob of unidentified XML in this location. It is then up to the client to parse through the XML, figure out what it means, and do something with it.

Now, when Microsoft technology is used on the client side, it knows what this XML means and automatically converts it into a .NET DataSet for the client to consume. But for any other clients, the XML coming down from the server has to be parsed manually. It’s not very fun, and no one wants to do it. Because of this, the use of .NET DataSets in XML web services is commonly viewed as a “Microsoft-specific practice” and not very cross-platform compatible (even though technically it can still be used by any client.)

So for Store 4, we decided to go in a direction that is more accessible to the mainstream. We now have clearly-defined XML structures for every request, response, and object we move across the wire. The services should now be completely compatible with any modern web service client technology. Except …

A single, ginormous WSDL file with everything in it is considered by some in the industry to be a bad XML practice. The argument is that the XML should be neatly parsed into a few separate files, and <xml:Import> tags be used to combined them on-the-fly into a single WSDL definition. Microsoft has adopted this philosophy, and the new WCF engine generates its WSDL files in a few distinct pieces – which is then left to the client to compile into a single WSDL contract. The problem is that some (usually older) client-side technologies do not yet support the <xml:Import> command. when these clients connect to a WCF web service, they download the main WSDL file but not all the other related pieces that contain the actual “meat” of the web service. Some clients view this action too as being Microsoft-specific; but it’s actually not, it’s an industry standard.

So – How can a client connect to SWS using older client technology? One flexibility provided to us by WCF is that we can expose our services through multiple endpoints without changing any code. So in addition to the default WCF endpoint (SWS.svc), we can also expose our services using the older ASMX engine (SWS.asmx) with minimal adjustments. And this second, ASMX endpoint generates an almost identical WSDL definition, but as a single file instead of split up into pieces.

Currently we’ve only exposed our main web service bundle in this way (SWS). But over the while we’ll be creating ASMX copies of our other web services as well. The .svc version is still the endpoint we recommend to all our clients; but if you’re having trouble connecting to it, then by all means give the .asmx version a try. Our goal is to provide complete compatibility with all platforms – and we’ll do what we need to do to make that a reality!