Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News Architectural Mirages

Architectural Mirages

This item in japanese


In his new post, AJAX+REST as the latest architectural mirage, William Vambenepe reminds us about a 15 years old vision that was supposed to revolutionize Web:

In that vision, your Web server would return an XML file with all the data; and alongside that XML, an XSLT (which describes how to transform the XML into HTML). The browser would run it on the XML data and display the resulting HTML. Voila! This was going to bring all kinds of benefits over the old server-spits-out-HTML model. The XML could be easily consumed by other applications (not just humans) and different XSLTs could be used to adapt to the various client platforms.

Time went on, and this idea was never really realized. Now fast forward to Ajax:

The XML doc is still there, though it usually wants to be called JSON. The XSLT is now a big pile of JavaScript. That model has many advantages over the XSLT model... It’s a lot more flexible, you can do small updates and partial page refresh, etc. But does it also maintain the architectural cleanliness of having a data API separated from the rendering logic?

Vambenepe explains why, despite of its seeming elegance and all architectural goodies, this model is not practical in most situations:

Clients of the same service support different interaction models and it’s hard for a single API to work well for all without sprawling out of control (to the point where calling it "one API" becomes a fig leaf). But if you want to keep the API surface small, you might end up with chatty apps.

But in Vambenepe’s opinion, this is only one of many problems of this approach. The other big one that he points to is the fact that such approach:

... forgo frameworks that integrate browser code and server code... not all Web developers want to think of their client framework and their server framework as two tools. Using them as one, pre-assembled, tool may not provide the most optimal code, but may still be the optimal use of your development resources..

Despite Vambenepe’s strong arguments, his post begs the question. What is the right way? Create/Generate a separate REST API for a given UI GWT style? On one hand, such approach simplifies UI implementation; on another, it requires a new API for every UI. Is this approach more scalable? What is more expensive? Implementing UI integration or back end API? There is another serious question that arises from this post. What is the right design approach? Implementing back end APIs and then design multiple UIs using it or start your design from UI and then define supporting APIs? Traditionally it seems that APIs’ implementation is more expensive, but the APIs themselves are much more stable compared to UI.

So, yes, it seems that a single API for all purposes is an architectural mirage, but a well design small set of reusable APIs can be used a foundation of many UI (Ajax) implementations.

Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • one API or one implementation?

    by Jean-Jacques Dubray,

    • one API or one implementation?

      by Jean-Jacques Dubray,

      Your message is awaiting moderation. Thank you for participating in the discussion.

      I am a bit surprised that in 2011 we still can write post or articles that seem to ignore the most fundamental principle (and differentiator) of SOA: the separation of the interface from the implementation. SOA actually encourages client centric "APIs" such that the same implementation can be used to support multiple consumers.

      Of course many "annotators" dismiss that very idea, for them SOA, is just a bunch of annotations on some Java or C# code. They even view an "ESB" as shoe box on a plate of spaghetti rather than a key architectural element that supports the separation of interface from implementation.

      Now, I was also disappointed by Wiliam's post (must be the first time, if I remember correctly) because he doesn't establish a clear separation between the context of the task supported by its own set of APIs and the "APIs" to the entities involved in the task. Nowadays, people build composite applications and consume 3rd party APIs so the programming model is clearer that way, but when you build an internal information system, few architects take the time to establish a clear difference between these two types of APIs and often mash them up within a single operation. That's the real spaghetti and this is why it is pointless to try to use a "single API" to support multiple clients with different context. That has nothing to do with XSLT, JavaScript or any other client-side programming model.

    • Re: one API or one implementation?

      by Adam Nemeth,

      Your message is awaiting moderation. Thank you for participating in the discussion.

      Well, I guess that web API adoption is more successful than most of the enterprise ones, because in web case, an API is a natural evolution of a webapp, separating its own view layer into its interface and implementation, whereas most enterprise systems try to create a separate API for 3rd party systems.

      The trick in the web case was, that there's an implicit interface between the template (View) and service (Controller) whatever you do. You can make this simply explicit, and annotate only to make them public/private.

      Another trick was that for the service (Controller) layer, you shall make the authorization abstract, so 3rd parties can connect.

      Then the separation of what belongs to the job of a service module and what does not begins, usually when making the page ajax-friendly.

      The architectural force which makes these work is that these services are all used by the main application as well, without a single exception. In an enterprise setting however, you create a service provider just to provide the service, for applications which you are not responsible for.

      I don't agree that there was no interface-implementation separation, they separated templates from their parameters, made sure templates can't think, made atomic services, all of these were needed for twitter and facebook to provide the infrastructure for their 3rd parties as well.

      It's only that the forces and directions are different.

      See collected at

    • Re: one API or one implementation?

      by Jean-Jacques Dubray,

      Your message is awaiting moderation. Thank you for participating in the discussion.


      it would be took long to argue here about it, but I have advocated for a very long time to consider MVC as a technical pattern, not a "business" pattern or if you will a "solution model" pattern. The real "interface" is at the Business Entity Lifecycle layer and at the Business "Task" layer. You need multiple interfaces to a business entity lifecycles because not all processes and task will have access or want to see all actions of the lifecycles. Some interfaces will be focused on scenarios.

      The general problem of the industry has been that people have tried to extend perfectly valid technical patterns like MVC (even his author came back from it) into the business world. A "controller" doesn't exist in the business world, hence the interface it offers in response to UI events or server updates do not offer any benefit to establish a "service" interface.

      All this is true for a Web App or for an Enterprise App, it has nothing to do with technical architectures. MVC is a tragic mistake, a real mistake: it makes it easy to build a system, but whatever is built from it is a) not reusable, b)unmaintainable. MVC was invented in the late 70s as the "Thing View Controller" pattern.

    • Re: one API or one implementation?

      by Adam Nemeth,

      Your message is awaiting moderation. Thank you for participating in the discussion.

      I'd like to discuss the following issues:
      - what is MVC about and what it isn't it about
      - what is the primary purpose of a software system and
      - why business lifecycle shouldn't be used as a primary design concept

      So, MVC is not a technical, but rather a philosophical pattern. In fact, it makes technology harder, as it is able to triplicate some issues whereas it should simplify instead.

      MVC [as defined in KP88] separates the abstract, conceptual system from its input and output handling, thus creating a boundary between reality and the abstract system world. Hence, a system can be described as follows:

      input+system state=output+system state'

      This is completely regardless of entity lifecycle or whatever. Entity life cycle is an abstract concept, it's an abstract model of business reality. How it's handled is defined by the views we provide on them, and we route user (or, to be more precise: actor) actions through controllers, which are in fact abstract representations of the user herself.

      What MVC isn't: MVC isn't the entities-services-templates webpattern. That also makes perfectly sense, however, it's rooted in structured programming [Dijsktra et al, 71] rather than in OOP as opposed to business entity lifecycle management.

      Now let's get us back what is the primary purpose of a software systems: it is to provide services that enables users to perform tasks in order to reach a business goal, that is, such a service can be to store and retrieve business information in an orderly way (like, a database), but such a service can also be to provide business entity lifecycle management. It pretty much depends on the task!

      In case we want to separate internal system state and expose task helpers grouped by services, entities and services separation makes sense. In case we want to go the OOP way, and want interacting objects instead, this still doesn't mean an object should be responsible for its own visual representation, as MVC pretty much comes from the smalltalk world [KP88, again], where objects interacting was the natural thing to do.

      Why business entity lifecycle shouldn't be used as a primary design method (in my opinion):

      Users don't think in business entity lifecycles. They think in tasks, methods to reach a desired end state of the world,where a given issue is solved, or all the informations needed to fulfill a desire are collected.

      Hence, an abstract yet strict representation of the lifecycle of the variables in the internal state of the system can quickly become the bottleneck, and pretty much kills usability, bringing the user back to the stone age of computing.

      We must never forget that our primary objective is to help the user accomplish real-world tasks, by creating an abstract, yet functional model of that world, according to which outside actors will react, and not the opposite way around, as however careful we are, these entities are artifical choices, and they are part of a conceptual model originated from only a handful of people,and the models of the individual actors (each single user, each single developer of 3rd party systems) are rarely coherent with it, creating confusion and unplanned usage all the time.

    • A mirage that should not be

      by Wang Rally,

      Your message is awaiting moderation. Thank you for participating in the discussion.

      Is "a single API for all purposes" really an architectural mirage? I think not. And in most cases what causes this to happen may be some artificial issues: anti-patterns used during API design, misunderstanding of architectural specification during implementation, and lack of deep dive during requirement analysis...

      And we should consider at least the following 4 points before we can finally draw such a conclusion:

      1.What an API is based upon? The abstration of pure business requirements, or a specific technical feature of an UI component?
      2.Are the input and output of this API laguage-neutral? As is mentioned above, although JSON is a special format of XML, but it may not be suitable for all cases, so why not choose a standard XML format instead?
      3.Have we really based our developement upon our customers' business instead of some technical staff's oral advice(especially an advice on a cool UI function that is not listed on the requirement list)?
      4.Is the communication channel between API architecters and API consumers healthy? and is there an operational way for architecture mining(does those cool kids of javascript guys really understand what is the API they're consuming for and how to use it)?

      So in my opinion, istead of draw such a MIRACLE conclusion so early, we should first take some investigations on the details of our processes.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p