The HTML Form is The Answer

I assert that REST already has a full web service description language built into it in the HTML Form.  In the most normal of cases, that of human web browsing itself, the HTML Form is already used in a manner declaring the exact parameters to be passed and matching the parameter to its user defined, dynamic value.  The HTML Form provides a standardized format to the definition of what query parameters are required for a given service.  For though the query parameters may be said to be self descriptive (REST proponents typically assert this, and SOAP advocates cite this as an argument against REST), without an HTML Form, a user or client will have no prior insight into the full set of parameters required or optional to invoke the service.  The HTML Form as RESTful service descriptor adheres to the text of the Fielding REST definition itself, where hyperlinks provide the “engine of application state.”  The HTML Form action parameter provides the hyperlink required to direct the transfer of state from the client to the service.

As for the common desire to automatically generate a service from a given HTML Form, taken as a web service description, we should look no further than the myriad of CGI languages and frameworks available, from Perl to C to Java to .NET to Struts and more, all of which provide to the developer a simple key/value pair for everything passed in the request.

WADL is Not the Solution

Why don’t I see WADL as a solution?  Because it assumes that the typical SOAP implementation of code/class generation and the corresponding marshalling and unmarshalling is what is wanted or needed.  I would assert that the reason that the number of RESTful web services implementations is growing and the reason that the web itself has been so successful is that RESTful services (or web pages themselves) are very simple and very scalable.  Simple in a way that WSDL, WADL, or any other heavy description language will never be.  Scalable by default in a way for which SOAP implementations must intentionally strive.

XForms

What about XML payloads then?  Well, you could of course declare an XML type for a parameter in an HTML Form, but that would not really meet the expectations of those that will otherwise develop SOAP based enterprise services, desiring a strongly typed description language.  The solution as it turns out is the successor to the HTML Form, XForms.  XForms provides a full MVC approach to web application or web service description.  An XForm can be represented as a simple HTML Form, or may take on much more complex capabilities, such as defining specific XML parameter types and sending XML directly to the server.  In this manner, XForms may be transformed to provide a human readable interface to a service, or may also be read by a machine in raw XML form to determine proper parameters and service location.

Concerning REST service descriptions:

• Debate: Does REST Need a Description Language?
  
• REST Service Description Conventions (RSDC)
• A discussion of the use of WSDL 2.0 to describe REST web services
• Describe REST Web services with WSDL 2.0
• Does REST need a service description language? – [asserts that a WSDL like language is not needed for REST]
• WADL REST API description language getting some attention
• Representational State Transfer (REST) Architectural Style

Concerning XForms:

• W3C Forms Working Group
• XForms FAQ
• XForms Essentials
• XForms Tutorial

Also interesting:

• XForms as part of the XRX Application Architecture  [Forms on the client, REST interfaces and XQuery on the server]

http://lza.zapthink.com/2009/02/09/soa-vendor-stack-analyses/

Posted via email from createTank Posterous

With or without the listed challenges resolved, we seem poised for rapid acceleration of mashups as REST APIs and “web sites as web services” concepts grow.  A real goal should be to implement services inside the enterprise to foster internal mashups.

The 10 top challenges facing enterprise mashups

Research has shown that often when cost is such an inhibitor, open source software (OSS) can help…On the other hand, everyone agrees that BPM/EAI/integration software is among the most complex software developed and offered in the market. Therefore—conventional wisdom says—it is no place for the OSS culture and development model…Conventional wisdom is wrong again.

createTank’s elemenope SOA framework is mentioned as one of the few FOSS competitors in the market area.

The elemenope framework is a classic integration server based on both OSS terms and conditions and OSS culture. It has been in development since 1999, almost since the start of the integration server era, and it has also enabled a service-oriented architecture (SOA) since before that term became popular.

Worth a read…
Can OSS Integration Server Software Enable EAI/BPM?
http://www.ebizq.net/hot_topics/open_source/features/8804.html
(Requires free subscription)

So, one might surmise that Jacquard Loom developers once felt insecure about the goings on in assembler and C development, and that C developers once lost sleep over OO and Java development.

So, supposedly, modern developers in general are living in fear that enterprise SOA directives will take their job away? Not likely feared. Not likely true.

Feared?

If anything, developers are ready to make their systems more efficient and/or agile. Only bad developers want to retain old disgusting decrepit code. Only bad developers like to hamper the efforts of forward thinking change. Don’t get me wrong, there are plenty of bad developers out there. But in the long run, bad developers usually become testers, don’t they? ;-P

True?

SOA is about business agility applied to IT productivity. Downsizing development staff is about as likely as OO reuse once was. If anything, IT staff will swell (and productivity with it).

From Sun:

WADL is designed to provide a machine processable protocol description format for use with such HTTP-based Web applications, especially those using XML.

A WADL file is an XML based language specification used to describe WEB-based applications. These files define resources, methods, requests and responses. The WADL project (https://wadl.dev.java.net/) houses the language specification as well as a wealth of other information including source code, examples and documentation.

wadl2java Utility

The WADL project also provides a Java utility called wadl2java. Wadl2java produces Java stubs from WADL files. The utility can be called directly from the command-line or as an Apache Ant task. At first I was a little baffled over how this utility worked. So, I decided to email the creator, Marc Hadley, with some questions. I was pleasantly surprised that he answered my questions. My concern was that wadl2java requires separate tasks and output directories for every WADL file. I’m use to having all generated classes contained within the same directory. Marc pointed out that even if he changed wadl2java to allow for this, the possibility still existed that a conflict could arise when two separate WADL files specified an XML element or attribute with the same name. Whichever WADL file was processed last would generate a class that overwrote the preceding. Wow, the light bulb went off, now I understood why it works the way it does. This was a conscience design decision to avoid class-naming conflicts, thus the utility must place these files in separate directories. In other words, if you were creating an application that consumes the services of two separate applications described by their own WADL files, two separate ant tasks would be required to produce the class stubs. Three applications would require three ant tasks, and so on. The generated stubs must be placed in independent output directories or the results from the second WADL would overwrite at least the end-point of the first WADL, as well as any other like-named classes. To avoid this, wadl2java has some built-in dependency checking that can be specified within the ant task.

Areas for Improvement?

Since the WADL project provides documentation I won’t go into details about the specification. However, I would like to point out a few areas that I found a bit confusing. When creating a WADL to describe an application, the ‘method’ reference has an ‘href’ attribute whose value must be prefixed with a pound ‘#’ sign. I see no practical reason for this requirement and would suspect that the WADL utilities can be programmed in such a manor to eliminate it. Additionally, the ‘href’ attribute actually is associated with the ‘id’ attribute of the ‘method’ definition such that the value of the ‘href’ attribute in the ‘method’ reference minus the pound ‘#’ sign refers to the value of the ‘id’ attribute in the ‘method’ definition. This is confusing because the labels used for these attributes are not consistent. Here I would suggest that both attributes be labeled the same. If it makes sense to use ‘href’ then both should be ‘href’. Otherwise, both should be ‘id’.
Another confusing area is the ‘method’ definition’s ‘name’ attribute. A ‘name’ attribute is usually an attribute used to identify something and is similar in function to how the ‘id’ attribute is being used. However, is this case, the value of this attribute really refers to the HTTP method type used to access the application. I would suggest that the attribute be labeled as ‘type’ or something similar.

Finally, the use of a ‘description’ attribute within the wadl2java’s ant task concerns me. This task uses the ‘description’ attribute to indicate the name of the WADL file one wishes to process. This is a little puzzling. Most Ant tasks I’ve seen make use of a ‘description’ attribute to provide a means for adding comments or further information regarding the particular task being performed. Maybe a better label for such an attribute would be ‘file’.

Overall…

Generally the WADL specification and its related tools excite me. I would recommend its use to anyone seeking a simple yet powerful means to describe any WEB-based application.
For more information about WADL please check out their site at https://wadl.dev.java.net/.

Originally published May 23, 2007.

Most importantly:
“We use an object binding framework,” he explained. “We use XSLT to
transform it in hardware. So when the XML comes in, all the validation,
all the business rules that are applied to it, all the transformations are
done, so we get a clean XML that is exactly fitting the object that we
want. So we can make one Java call, say un-marshal, and we have the
object, lo and behold. We don’t have compiled classes. We have no mapping. Nothing.”

What the Classics Say

While this is not untrue, a review of classic architectural writings reveals a fuller and more enlightened perspective. In point of fact, Architecture is about the spaces and the structure and the foundation. Physical Architecture does in fact concern itself in no small manner with the structure and foundation of the building. Without a solid and proper foundation, even the best and most suitable “spaces-based” Architecture will fail. The spaces based viewpoint might come from the fact that in the world of physical Architecture, structures and foundations are usually a known quantity, as a great deal of experience has been recorded over the past few thousand years. However, whenever a new material or technology is introduced, inherent unknowns often produce failure. With this failure and its study comes further understanding.

Software Architecture

In our world of software and systems Architecture, the foundation is the technology upon which one builds. Without an experienced based, solid foundation, even the best system will fail. Unfortunately, we do not have the advantage of thousands of years of direct experience to tap in our decisions of foundation and structure as do the physical Architects. Many modern software Architects start and end with what they already know, or let developers, politics, or circumstances decide. This is a short-sighted path. At createTank, we’ve seen success in recommendations based upon information from two primary sources:

1. Direct experience on hundreds of major projects in all variety of form and function.
2. Interdisciplinary Architectural research.

In this way, we can put to good use those abstract principals refined over thousands of years of physical Architecture, made concrete and applicable through direct experience doing modern, “dirty hands” work. When combined, these sources provide a more holistic architectural perspective. We are not perfect, nor claim all answers, but the proof is in the pudding, and one well built system is worth a thousand white-board rectangles.

The createTank perspective

Architecture is not only about technology, but it does concern itself with technology. That is, Architecture is not only concerned with the space, but also the structure holding up and indeed defining that space. This is the technology aspect of architecture. Without a solid foundation and structural components, any building or structure will fail. Enterprise Architecture’s virtual constructs are no different. The best design, the best architecture, will be hampered by a weak foundation, whether in the O/S, software language, or framework chosen. This is stated in confidence, because although the actual system may indeed function well, lack of scalability, maintainability over time, or agility to integrate with other systems will catch up in time and prove expensive or fatal.

Summary

In the end, ZapThink is not necessarily wrong in their assertion, the assertion is just incomplete. It is easy to understand as they are trying to highlight the business value of SOA. However, downplaying the role of technology in SOA to such an extent is unsettling. Walls are important in physical architecture, and technology is important in your software architecture. It might not be continually considered the most important component of your architecture, but an architecture should only be considered healthy when the foundation (its technology) is trusted solid and sound. Walls and structure, as too, technology, hold up and define the space or functionality designed. In essence, a good architect MUST understand the technology involved, including which technology best fits a given problem, in order to create the best possible system. This is absolute. In your projects, you would do well to place stock in the hire or counsel of an architect with extensive experience in the technologies involved and with the ability to communicate the lessons learned therein at multiple levels.

…the traceries had caught the eye of the architect…up to that time…his eye had been on openings only…Now, the great pause was at the moment when the space and dividing stone-work were both equally considered — John Ruskin, The Seven Lamps of Architecture, The Lamp of Truth, Section XIII.

^* “Physical Architect” is used here to jointly differentiate architects of physical structures (e.g. buildings, houses, industrial complexes, skyscrapers, etc.) from architects of more virtual structures (e.g. software systems, software applications, enterprise IT systems, etc.).

createTank Attends…

After much thought, I attended the LZA Boot Camp in Baltimore last month (April 23-25) for what boiled down to two hard, tangible reasons:

1. To widen my horizons (and createTank’s) by concentrating on a broader and more business oriented slant toward SOA (createTank has historically focused on research around the implementation questions of a SOA, or software architecture in general).
2. To attain an architectural (and specifically a SOA) credential to differentiate createTank from those that are “architects in name only” (see Vitruvius’ Education of an Architect to be discussed here at a later date). The fact that this credential would come from such an independent and objective organization as ZapThink was quite a convincing point.

I did in fact get what I came for … I saw a review of SOA from a different perspective, and I am now a Senior Licensed ZapThink Architect (Senior LZA). However, I did get more than I expected. Specifically, I found in my notes and “take-backs,” a refinement in some of our positions at createTank. I also met quite a few good Architects and Technologists from across the country and around the world that should hopefully prove to be good friends with which to bounce and share architectural ideas. I’d been looking for a community such as this for a long time now.

Since Then…

I’ve finally found the time to review the notes and complete my internal reports. They really did pack a lot into the three days. The time betwixt has allowed me a good deal of dialogue with other Architects, including our own Larry Liberto, which has further refined the positions and ideas of interest. I should be posting many of our findings and related interesting points here over the next few weeks.

Concerning the refined positions, most are agreed upon by createTank and ZapThink, but createTank seems to have a slightly different take in areas which may prove interesting. This is likely due to our technical and implementation specific background. It might be an over simplification, but we tend to ground our architectural advice from below in our implementation experience, whilst ZapThink tends to support their architectural advice from above with business experience. Of course both methods are legitimate and useful, but they are different. There is a great deal of overlap, as there should be in architecture, but by researching the differences, we may refine our positions and learn more from each other. I’m somewhat amazed at how we’ve come to so many of the same conclusions about SOA and Architecture in general while approaching the problem from such different perspectives. I’d speculate that the common factors are [1] experience and [2] the ability to be honest about that experience. It seems that many groups (especially vendors) let marketing get in the way of that which is best left in its simplest state.

We at createTank have been big fans of ZapThink for a while now as one of only a few organizations out there that were not trying to sell SOA as a set of products, but rather trying to reveal the truth behind its power. I would definitely recommend the LZA Boot Camp to any genuine or aspiring Architect out there with an interest in seeing SOA framed in an objective manner. I’d also recommend it to organizations looking to implement SOA internally, as a vaccine to the seemingly endless vendor sales pitches in store for them.

ZapThink: http://www.zapthink.com/

ZapThink LZA: http://www.zapthink.com/lza.html

ZapThink Architect Resource Center [ARC]: http://www.zapthink.com/ARC-view.html

Next Scheduled LZA Event: Sydney, Australia May 28-30, 2007
Register: http://www.zapthink.com/eventreg.html

As with any SOA implementation or legacy integration, the team wraps the legacy implementation(s) with the chosen SOA technology or framework, adding necessary new functionality alongside. At some point in time after the wrapping takes place, legacy implementations of services/operations deemed to perform insufficiently may be completely replaced by new implementations just as with the regularly described “wrap and replace” method. However, the “wrap and replace” description leaves out the very real possibility of the retention of legacy services/operations which continue to perform and deliver value. These implementations may remain in place working transparently alongside new implementations.

In the illustration, we see two legacy systems (Legacy_A and Legacy_B) and new functionality integrated into a SOA Framework. Within the systems, multiple services or operations are marked in red as candidates for replacement. These are the “squeaky wheels.” Notice that a good portion of the legacy implementations could remain in service indefinitely. This shows the agility that SOA provides, in that the team is not forced to replace the legacy code until they have a “real” reason to do so.

The fact that the legacy implementation can remain around indefinitely brings us to one final point of any good SOA integration, that the system need not be completely replaced or rewritten every major industry cycle. For example, if Legacy_A was written in COBOL in the 70’s, Legacy_B was written in JMS in the late 90’s, and the latest system is written with SOAP over HTTP interfaces, a future implementation in the fictional “Protocol-X” could still retain some or all of the existing implementations without rewrite. This is an important point, because new languages and technologies will continually overcome what we are now implementing.