Elements of API style: Daigneau talks REST vs SOAP

Web services APIs have vastly expanded over the years to include a host of REST-based methods. Resource and Message APIs have become common in addition to SOAP APIs.

Despite the expansion of Web services development in recent years, the area has lacked a concise catalogue of common practices and methodologies. Enter “Service Design Patterns” (Addison-Wesley, 2012), and SearchSOA.com’s Jack Vaughan spoke with author Robert Daigneau about business and development, REST and SOAP. Daigneau knows whereof he speaks; he has served in such prominent positions as director of architecture for Monster.com and manager of applications development at Fidelity Investments. He now holds the post of director of server applications for BlueMetal Architects.

In the past decade of SOA and services development, the actual matter of ''how you do'' services has become a bit more of a repeatable process. But it is still something of an art. That is borne home in ''Service Design Patterns.” In the book, Rob Daigneau sets out to create a codification of techniques that people have tried over the years for application development and integration based on services.

Using the connecting thread of software design patterns - the book is part of Addison-Wesley's patterns-friendly Martin Fowler Signature Series - Daigneau identifies some recurring problems, wraps them in context, and outlines ways of solving them, marking this as a very useful reference for the services design team.

Web services APIs have vastly expanded over the years to include a host of REST-based methods. That is a far cry from the originally popular notion that SOAP RPC APIs were the one true way. As ''Service Design Patterns'' enumerates, Resource and Message APIs have become common too.

Stylin' with APIs: RPC, Message and Resource

For enterprise architects and developers trying to decide on the right API style, Daigneau’s book suggests examining each within its own context of use. RPC APIs, Message APIs and Resource APIs all have different approaches. The question architects should ask is which API style works best for a given problem, Daigneau told SearchSOA.com in a recent podcast interview. He also offered the following explanations and advice for those weighing their choices:

  • RPC APIs are the ones that most developers out there are familiar with. In this approach, we essentially create a service with an external interface that’s derivative of some procedure out there which is hosted on a server. We can find messages and identify them within the remote procedure to execute. [RPCs] also have a few sets of elements in that message that essentially map directly back into the parameters of the remote procedure. This can create a rather strong coupling between the client and the service.
  • Message APIs really try to break that coupling apart a little bit more. Here we may be sending commands, notifications or other sorts of information over the network to a service while avoiding the direct coupling to these remote procedures. In this case, rather than creating some service with an interface derived from the remote procedure we say, “Well let’s just create an interface that stands alone.” The messages should carry all the information as required about a particular topic, a talk to execute, events, things of that nature. When this message is received at a particular URI, the service will interrogate the content of the message to essentially route it to the correct handler. There really is a level of indirection between the service and the actual procedure that’s executed. Now, that really promotes independent evolution between the client and the server—quite a bit more than your RPC API style does. But, as you can probably guess, it requires a lot more skill. You have to really kind of understand some things at a lower level. You may use SOAP and WSDL or you may not use SOAL or WSDL. So the time to development might be little longer than your RPC style, but, again, it promotes evolution quite well.
  • Resource APIs use a requested URI and HTTP server methods to decide which media type is requried. The style adheres to so-called REST architectural styles.In such instances, JSONis increasingly used for data handling. The Resource API is a good choice when dealing with a wide mix of clients.

From workflow model to runtime system

Even after architects and developers have figured out the best techniques for service-based application development and integration, other challenges remain, as was clear in a sidebar discussion we had with Daigneau on BPM. Challenges remain where the development side meets the business side. The issue is familiar - it is about the gap between "thought and expression" that plays out in integration today.

The fact is that there remains something of a chasm between design-time modeling and what happens at run time, according to Daigneau. The gap is everywhere, but it may be very vividly seen in the world of BPM, where business models are converted to runtime systems.  

BPEL has been a player in this space, used as a services orchestrator, but attention now is shifting more to BPMN, a notation for modeling. "A lot of people have been hoping we could eventually give modeling tools to business analysts, that they could click a button, and, at the end, the code gets produced that makes that stuff magically come to life," remarked Daigneau. "And I think we've found out that that doesn't work out so well. There is this chasm between the higher level ideas and the best way to implement those things. A lot of it has to do with the nature of [software] services themselves."

And what is the nature of those services? Services are very expensive to call on a technical level, he replied. They require serialization, deserialization, data transmission over networks and latencies. They invoke the issue of dealing with partial failure, and so on. So often, what may be drawn in a workflow, must be implemented by developers in a slightly different way, Daigneau said. But with BPMN 2.0 today, we see another effort to do magic with models.


What are your thoughts about Web services APIs? Let us know.

Dig Deeper on Topics Archive