For whatever reason, it got so popular today that many people equals the future of Web Services to REST. It’s true that REST based API is easy to understand with simple HTTP request/response messages in XML format. You can get some work done using text editor plus web browser.

But REST does NOT scale. When the programming model behind the API gets complicated, it cannot easily handle the complexity because REST is more a style than a spec for designing an API. It does not offer a systematic way defining the interfaces like WSDL for SOAP. All the interface descriptions are in text, meant for consumption by human, not for software tool. Some REST API provides XML schemas for the request/response messages, which is a step forward but not enough.

Having said that, REST is still a good style for a simple API and intended to be used with scripting languages like PHP.

Now, what is the rescue for a complicated API? I think SOAP is a much better choice than REST there.

Although SOAP, with its sophisticated WSDL, seems much more complicated than REST, but that is only for human. For the computer, WSDL is easy to handle. Good news is most developers don’t need to read WSDL. They can rely on tools to generate stub code for developing applications. While working on the high performance Web Service Engine, I had to read the WSDL for code generator because the AXIS does not perform well; otherwise I shouldn’t have had to neither.

By its very nature, SOAP is procedural and does not support OO programming. If you want to implement OO, you have to design the interfaces very much like the OO code in C, where you have the struct as object while every function has a pointer to the struct. Even it’s doable in some way, but it doesn’t look natural at all, especially when you use the stubs in real OO languages like Java. That is where VI Java API comes to help.

In general, OO is the choice of modern APIs. But SOAP does not support OO. You can see the gap there. The gap is not so noticeable today as most SOAP APIs are simple, too far away from the complexity of VIM API. It might change in the future. By then, an extended SOAP with OO support will surface and bridge the gap.

Technically supporting OO in SOAP is not big deal. We already have a successful implementation in VI Java API. The key is to extend the WSDL to include the type definition (class) beyond the functions (method). As lack of type information, the managed object model is coded manually in VI Java API.

True RESTful web services DO scale. When designing RESTful architectures, the developer should not simply construct some well-formed and fancy URI schemes, instead he has to think about the domain he’s going to translate in a resource oriented way. Thus thinking deconstructing the domain models into true resources, entities and — when absolutely needed — explicit algorithms. Doing so the developer should break the domain model down into smaller chunks that accord the principles of REST which in turn result in a better horizontal scalability. Compared to Service Oriented Architectures like SOAP or RPC, where the developer tries to map the business logic nearly one-to-one, a RESTful webservice is designed somehow in an extremely object oriented way, where only the standardized HTTP verbs GET,UPDATE,POST and DELETE (not to mention HEAD,OPTIONS and the HTTP1.1 headers) are allowed to be used to describe how the resources (=objects) are controlled/handled. This allows clients (likewise humans and agents) to use truely RESTful (I repeat “truely” because most APIs that are described to be RESTful basically are not RESTful; most of them are pseudo-RESTful or REST-RPC hybrids) APIs without having to know the entire business logic. And — in order to make RESTful APIs usable by non-human agents — a RESTful API must be interconnected. SOA are something like a bunch of blackboxes which are generically not interconnected with each other. RESTful webservice in contrary must offer the client two essential information for each resource:

1. Metadata about the resources — most basically which operations are allowed to a specific resource and

2. Further links that allows the client to reason about how to navigate through the API and to discover the available information without the need of a “masterplan”.

NEED HELP?

My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__ doublecloud.org.

Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.