API Design: Expose XML or Objects

Question

We're embarking on a new middle tier service that will allow internal client systems to create and update and query records in some underlying data stores. The service will aggregate as many as 3 seperate underlying datastores. For the purposes of this question assume:

Data store #1: Proprietary XML Database.
Data store #2: Off the shelf relational Database.
Data store #3: Flat file store (files stored as binary).

The clients will not know (nor care) which datastore they are querying/udpating. The new service will make that decision. My question is this: Should my API expose XML or objects? E.g. The new API will have an add method. Assuming that our system is a car storage system, then the add method of the API may look like this:

AddNewCar( CarObject car )

or, it could look like this:

AddNewCar( string carXml )

Now, even though the 2nd method is weakly typed at entry, the XML will immediately be validated against schema as a minimum.

The new service is going to be written in C# (not decided yet on which version, but probably 3/3.5 with WCF). Clients of the API could be C#/VBA/VB.Net/C++/Java).

Any more details please let me know. Thanks

---

Update: Note that the API will also be publishing XML over a message bus. E.g. when a new car is added the car XML will be published so that anyone who is interested in new cars will be notified.

Answer 1

Certainly the stongly typed approach will be easiest from an end-user-developer perspective which is what I would prefer. However, if ultimately everything is converted to Xml behind the scenes or you are unsure wich approach your clients will take, I'd definitely recommend you support both.

Answer 2

You shouldn't expose the XML as this fixes your format and any future decisions you may face regarding infrastructure. I would always go the strongly typed route to ensure you properly abstract your implementation away from usage.

If you take the XML route and find out, part way through development, that the XML has to change for some reason, it will be much more difficult to change all uses of your API to correct that problem than if you strongly typed the API and hid the XML detail behind the objects.

Answer 3

You should create the API using objects and leverage WCF to provide an XML API if needed.

Answer 4

You should create an API using Objects, and then create a web service interface around that API (e.g., for Java you would use java2wsdl on your interface, and then wsdl2java to create a skeleton server-side implementation or client-side implementation, I'm sure that an equivalent methodology exists in WCF) that all the other systems can query.

As you have multi-language clients, I think a web service is your best choice, and (ignoring the business logic implementation) is only a few minutes of work on top of your API. You can distribute your wsdl or xsd files to all the client software's developers which they can then use to interface to your system simply and quickly.

Answer 5

I'd say expose an object API. Although not for the reasons mentioned in another post above - that of exposing XML resulting in a fixed format that is more difficult to change.

Arguably, an API of strongly-typed business objects is as difficult to change as XML - both will require re-compilation and re-building. So that isn't the reason why you should discard XML.

The reason - IMNSHO - is that of level of abstraction. At the API level, you are talking in terms of what business objects or services can perform what actions on what other business objects. Therefore, the API must talk in terms of business objects.

As mentioned in another post here already, you can always back the business objects with XML representations. Keeping the XML representations of your business objects and services at a lower level of abstraction that your API will provide you all the flexibility of XML while at the same time allowing you to build a higher level API that has good semantics.