API Design: Expose XML or Objects #2

Question

I recently asked this question: Expose XML or Objects - thanks all for the responses.

One point to clarify.

• The API will always be accessed remotely (i.e. as a service), most probably via webservices or WCF.

I agree that in theory a strongly typed API exposing objects as the inputs/outputs is the right way to go. However, I feel that there is still an argument to be made for exposing XML. As I see it the reasons for using XML are:

1. The business rules can be written by business analysts in Schematron.
2. The interface is weakly typed, but as soon as it is called the data can be validated against data and business rules.
3. The service's implementation will be simpler. There won't be any need to create an domain object model.
4. The XML schema is already defined (we have a data dictionary of schema).

5. Using web services technology means that an XML based API will not need to change as new car 'types' are added, e.g.

   void AddNewCar( string newCarXml )    
   string[] GetCars( /* some query conditions */ )
   

   If we used an object based API then adding a new type would require a new query method defining the possible derived types that could be returned (see extending web services). Updating the web service like this would require this services and all existing clients to be rebuilt and redeployed.

What does an object based API give us? A strongly typed declarative interface. It does not provide any more abstraction than XML (XML is itself an abstraction). What does the object based API cost? It costs an entire set of domain objects which will need business rules and data validation.

So, what is my question? Give me an un-defeatble, unarguable reason why I should go with objects.

Answer 1

If you're looking for an argument in favour of XML (not that I am particularly in favour of XML) are:

• Exposing the XML and providing an XSD is self explanatory when it comes to data. You can pass off all the data in that form, it's self documenting and can be validated reasonably simply.

• I can write a bunch of safe code against my database or code model and I can release the data in a self contained and safe manner to other business units that requires minimal further documentation or explanation.

• It's so easy to read that often you can read it as easily as you could read the documentation or code comments.

The arguments against it however, go on and on...to name the worst offenders:

• Overly verbose.
• Huge network overhead.
• Require an understanding of an extra technology, perhaps needlessly(?).
• The more complex you make something, the greater opportunity for errors there are.

Answer 2

• Objects can perform better (thinking binary serialization here).
• Objects can have stronger simple type validations.
• Objects allow you to put the validation and business rules closer to the data structure definition.
• Objects by their nature allow you to write simpler business rules and validation, since much of that is embedded in the object definition itself.
• Objects can also define behaviors.
• .Net makes it simple to turn Objects into Xml and back again via serialization, giving objects most of the same benefits as xml.

Answer 3

When you expose plain XML, all your clients will need to write code to generate and parse that XML. Easy in some languages, a PITA in others.

But most languages have web service APIs that can take wsdl/xsd and generate a full client library in seconds. Sure, they'll have to write a mapping utility to map from their internal model to your model to interact with you, but that's to be expected.

Your web service will handle all the Object<-->XML stuff internally (for the client's view), you won't need to worry about SOAP and all that. You'll define your interface:

void addCar(Car newCar);
Car getCar(String make, String model, String year);
void removeCar(...);
List<Car> getAllCars();

which makes a lot of sense to your clients. They grab your wsdl and generate their client libraries in Java, C#, PHP, Python, etc.

There's nothing stopping you adding:

int addCarXML(String carXML);
String getCarXML(int carID);

But why add two levels of webservice cruft - first the wsdl, then the xsds for the XML schema...

Answer 4

Strong typing in fact any typing at all for that matter exists for the sole reason that the programmer does not make any stupid mistakes (eg. passing a string to a function expecting an int etc). On top of that this happens in compile time and costs nothing at runtime thus producing efficient code by avoiding runtime checks (eg. for proper casts) and avoiding abnormal behaviour at runtime for unmanaged code.

Like you said Xml can be used to define a replacement object model but this object model needs to undergo the same checks at runtime to guarantee reliability to a certain extent. But this has a certain finite runtime overhead.

Having said that all I want to say is that the final choice is yours. Are you willing to abandon the safety (and sometimes peace of mind) afforded by a "rigid" object model or will you be more comfortable with a more flexible but can-shoot-yourself-in-the-foot object model? XML requires greater programmer discipline and alertness (thus making it a chore to use IMHO).

The "object based" API is not as rigid as you think, automatically generated XML schemas maynot be doing what you really want them to do. Object based APIs can be made just as flexible as XML based API if they have been designed well. Dynamic typing can help too sometimes.

Answer 5

Take a look on the web for articles about Contract-First Design, the Spring web site has a good example. I am developing a new web site right now and have taken the approach of starting with and XML Schema and using it to design my application domain model. XML is an excellent for sending data between disparate systems or even layers of your applications. It is programming language agnostic and there are many tools for editing, designing, and implementing XML based designs.

It is verbose, but in the scheme of things the verbosity is a minor annoyance. It can create large files, just compress it. There is more overhead in processing it, but we developers are always trading pure performance for ease of use, maintainability, extensibility, etc.

Answer 6

Here's another random thought - use neither ;-p I'm thinking of other exchange formats. I've done a lot of work lately with protocol buffers - this offers contract-first usage (via a ".proto" definition), but is designed with safe extensibility in mind - i.e. you can design things to pass through unexpected data without breaking or loss. Unfortunately, the main protocol buffers spec doesn't actually include inheritance, but my implementation (protobuf-net) shims this via extensions.

Whether it is mature enough depends on the scenario - I just thought it might be of interest. As an aside, it (protobuf-net) also plugs into WCF for the convenience of a pre-rolled RPC stack ;-p