REST Fans Categories

 First of all, let’s clarify a couple of things.

1. This post is not intended to list “bad ways” of thinking about REST, but to list the actual way people really think about it. Some of them are perfectly correct per REST constrains.

2. From articles, presentations, discussions and the like, I extracted commons ways of thinking, and tried to categorize them. So, this is a totally subjective classification.

So, let’s start.
People know about REST. Many are trying to get into the REST world for the first time, some other have more flight hours, still not so many had read Roy’s dissertation. Even more, some of the ones that actually read the dissertation, may think about REST in different ways.

Usually, when in a discussion, the same concept may be understood differently by the participants, which yields in non-useful conclusions. This may be actually true about REST. That is why I composed the following list of  “ways people understand REST”. The list may help the reader to find out where he stands in understanding REST, and how may other people understand it. Also, it may show how some people is using REST.

First, an cautionary word: the names I use are not intended to make fun of people, but to be easy to remember.

The list is divided into three major groups: The API makers, the Mappers and the Fad Followers. This last one may seem a bad one, but it is actually a normal one, trust me many people fall in it.
Then, each group contains categories. Those categories may be present in more than one group, since the characteristics may fit both groups.  Finally, people may fit in more than one category, since the work is complex in the world of REST to reduced to just one characteristic.

Here is the list.

Major Groups 1: API Makers.
People in this group I find them everywhere. Most of the time they have a system, usually not built thinking on REST at first (REST as an afterthought), and they want an API created to access that system. They usually think about REST like an API making technique or recipe, for the web.

Categories:
 - URI Jugglers. These are the ones that think REST is all about creating URIs, and nothing more. So their discussions are solely focused on URIs, and their presentations are about URIs definitions. One way of spotting this category is when the application API is documented as a URI construction process using templates

 - RPCers. This group think REST is a way to map RPC in disguise using URIs in a web API. The most of them don't know they speak RPC at all. Easily spotted when you see the API defined as a set of calls using a URI construction. Most typical is a URI format that includes the actual method name or action, followed by several parameters. There are many of them coming from SOAP based web services (the RPC kind), that made the change believing is easier to define the RPC call in a simple URI than using the complex SOAP envelope.

 - Exposers: This type is repeated below. Those are the guys that think you need to expose things in REST using resources. So REST is an API for exposing things on the web. They usually look for objects or domain entities, but mostly processes or methods, and expose them using a URI formatted call. The slight difference with the RPCers, is that the exposers may not use RPC, but still expose the processes and entities through an API. 

 - CRUDers: Another repeated group. They think REST is a web API for CRUD. The similarities of the HTTP operations and the CRUD ones, plus the reference of resources as Data elements, support this way of viewing REST.

Second Group: Mappers.
This other group may use the API idea, but they actually think REST is a way of representing things and thus the work to be done is to map everything using that new way. Interesting?

Categories:
 - CRUDers. Again, the idea is that CRUD operations can be mapped naturally to HTTP operations, and that makes it RESTful.

 - HTTPers. They believe REST is HTTP. Deep enough. This category is hard to spot, since many people talking about REST implementation may talk much about HTTP, but think REST is far more than just the protocol.

 - Exposers. Again too. They usually try to map all classes, data entities, elements into resources, and then call their systems RESTful. This category includes people that take into account REST constrains, and also people that just maps the  domain to resources.

Third Group: FAD followers.
This is a group that is identified by themselves. That is, they expose what they think explicitly. Usually, they tend to follow a lead or the current business idea.

Categories.
 - Standard Haters: Here you have all those that think Standards are evil and that REST is an anarchy where you have the freedom to do whatever you like, so they follow REST doing whatever they want.

 - KISS lovers. These are the ones that like things to be simple. And someone told them REST is easy, so they follow doing easy things with URIs. There are lots of URI jugglers in this group. People here may not follow all REST constrains when they get complex enough. The idea is to keep the API or system with not much complexity.

 - Servicers. They think Services is good, and someone told them REST is a way to do services without SOAP. So they follow. There are several RESTFull service creation techniques. Many RPCers in this category too.

 - BuzzWorders. This is a vast majority. They like buzz words, so they follow REST just because it is cool and all people talk about it.

Is there some one I'm missing? Well, yes, probably the group that knows REST as it actually is and understands it. That may be a one person group (yes Roy).

What do you think? Do you find yourself in any of those groups? Which other category may you add?

The Agile missing point and the Waterfall Illusion.

What if everybody is wrong? Well, not everybody, but majority.

Reading Kelly Water’s Post about “Agile Project Management: Avoiding The Waterfall” I came to think about this. Almost nobody claims today that they are following waterfall, because of the very bad connotation that word now has, but not actually because they understand what are they doing. Same thing for Agile followers.

From the post, I rescue that any process that has phases reassembles a waterfall. From actual presentations, blogs and discussions, Agile often means just following methodologies like Scrum, Lean or XP. Now I question: are we right about this? Let me see if we are, or not.

Waterfall is a term, it seems nobody knows who coined it, related to a phased methodology. Dr. Winston W. Royce wrote about it (without given that name), describing an ideal form that was not so good . The phases were the requirements gathering, analysis on those requirements, system design, coding, testing and operation. The ideal was each step may iteratively cycle with the next down and the next up, in little steps. The flaw was it was usually the case that testing will not just go back to coding, but it may go up till design, and from there, jump back to requirements gathering again. That flaw (the large back jump) was caused not because the phases, but because the testing phase is where the actual product is finally validated against design and requirements.

The problem is, there is no solution to this. We can dilute or minimize the impact of the testing findings, using several techniques, but we cannot avoid it. At any level, team or individual, the same steps are repeated: I see what it is needed, I analyze what is possible, I think on how to do it, I do it and finally I check if it works. That can describe the process of developer creating a simple three line method! That is, phased development is there, everywhere, and that is not the problem. The problem is when that phased process is done in a way that the impact of facing reality with needs is too big that multiplies the work and the cost of the back jump.

So, the waterfall illusion is when you think that rain is not a waterfall, simply because the raindrops are so tiny you don’t see them fall individually. But they fall anyway. It means, people that think eliminating the analysis and design steps and jump into coding breaks the phased process, I’m sorry, it doesn’t, it may avoid a large body of water fall into one place, but will make millions of little bodies fall everywhere. See the point?

Ok, there is another idea into this, and that is to make the water flow up. You start coding, with no idea of what you need, and then the phases are completed backwards. (Hey! If you want to start really backwards, then start by testing! Oh, yes, we have TDD). The code will make a design “emerge”. The next logical steps if to create requirements that match the design. Well, I guess that does not work. In that case, the requirements are still presented before coding. So the new phases are: requirements, coding, design, testing. Or, requirements, testing, coding, design, testing, coding, design, etc. Anyway, we always have phases.

Now, Agile. In the Agile Manifesto the idea was to value common sense upon theory. That is why “individuals and interactions were valued over processes and tools, working software over comprehensive documentation, Customer collaboration over contract negotiation and Responding to change over following a plan.”. Nowhere on those lines there is a mention of chaos process over phased process. Where is the missing point? Well, actually in three places.

1. Comprehensive documentation was assumed to be the design’s product. So, design must go, correct? Well, that is not true. The idea behind this is to prefer creating working software rather that documenting. Actually, creating working software requires you to think first on what do I need to create software for, how can I accomplish that, think how will I do it, do it and then check if it works. You can do all that without opening a word processor, right? Working software is not any software, but the software that delivers the business value, and that is not produced just by hitting keys.

2. Customer collaboration over contract negotiation seems to define the negotiation to be a non collaborative task. Actually, any customer involvement implies a contract (or mini contracts), which is the definition of what to do, and who will do what. Collaboration does not mean the client will bring coffee, or will help writing the code. It means active communication to shape the bush with little cuts. The client says the overall figure, then supports indicating the little branches you may cut further. Contract and mini-contracts.

3. Responding to change over following a plan does not mean going into chaos. The following a plan refers to follow a line without looking at changes in time. That is flawed thinking, the plan may perfectly be to respond to change in an organized way, validating each time to improve the next one. The plan is simple: we decide as we go, following these principles.

All the above is in the principles.
“Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.”
“Continuous attention to technical excellence and good design enhances agility.”
“Business people and developers must work together daily throughout the project”
And
“At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.”

Now, let’s talk about project managers and architects.
I understand many agilistas think they need to disappear. Yes, YAGNI. Architects are document creators and thus have no business in Agile. Project Managers are plan followers thus they are not welcomed in Agile world.

Of course, that is not correct. I mean, the stereotype many people has about architects and project managers. In a team, you need different roles. If you have only coders, and all people just code, you have an incomplete team. Roles are not fixed either, you can have four, ten, twenty different roles in a team. Each person performs a type of work, needed to complete the main goal.

So, does that mean Architect and PM are roles? No, they are professions, and each one plays a role in the team. And no, an architect is not the one to write design diagrams, and the PM is not the one with MS Project under his arm telling everyone how to type its code.

An architect is the one that owns the architecture, that is, knows what the structures and organization of the functional elements and other architecture issues, are. Not only that, he is responsible of assuring the business goal is met, either changing the code that builds the architecture or changing the architecture to match the code.

The PM is the one in charge of measuring everything, keeping an eye on evolution, times, resources needs, organization of meetings, pending issues, team problems, process glitches, and a long etc, so coders wont need to worry about those things.

Closing this long post, I can summarize:
1. No, there is not only waterfall and the good guys. Water is falling in all projects, we need focus in minimizing the bad effects.
2. No, agile does not mean following a methodology and getting rid of good guys like Architects and PMs, but understanding the common sense of the manifesto and apply it to improve development.


Cheers!

Quick Post Edit: Reading at this, you may think I believe all Agile people thinks the same. Well, no. I was practicing agile principles even before the name was coined, and find out those are misunderstood by a lot of people. Fortunately, not all of them! So, Agile is the way to go.

Willy's SOA Manifesto

Yep, my own. Although it may have some shared ideas, this is not a group agreement, nor the savior of what is now known as SOA (which is what is being done so far), nor something made for others to follow. It is just what I believe, what I follow, and what I teach each time I can.

So, here it is.

SOA MANIFESTO

1. Commons.
a. SOA is an acronym composed of the words Service Oriented Architecture, which relates to an architectural style that is based on the rules of the service metaphor.
b. A Metaphor is an application of the figure of speech concept to the IT design discipline. Using metaphors in architectural design actually refers to observing the rules of behavior of a particular entity in the business domain, and mimic them with an architectural element.
c. A Service is conceived as a cohesive (and coherent) business functionality, technologically neutral, offered through a uniform interface. A Service is a plain, homonymous metaphor of a business service.
d. For an architecture, Orientation describes the guidelines, principles and decisions that are based on the rules that govern the metaphor behavior.
e. The Architecture refers to an actual style that defines the architectural constrains, suitability and consequences of using it.

From (a) to (e) :

SOA is an architectural style whose components, constrains and principles
are driven by the service metaphor.

2. Delta
By definition, and in contra-position from some usual implementation, SOA IS NOT:
a. An Indirection Layer for interoperability.
b. A Decoration Wrap for legacy code accessibility.
c. A Component from a whole that represents one architecture instance
d. A Service Group or container of services
e. A Business Process Container.
f. A Modernization Agent
g. An Object Distribution Technology
h. An Antagonist of REST
i. A ROI salvation
j. A Way of Life, A Philosophy of Doing or a Trend (It is an architecture style!)

Corollary of (j): SOA cannot be killed, it cannot just die.
It can be suitable for a problem or not.

By definition, and in contra-position from some usual implementation, Services ARE NOT:
a. Necessarily Web Services as defined in the WSA.
b. Ways to implement RPC nor RMI.
c. Exposed Methods or Objects.
d. Defined by the process they execute
e. Necessarily Stateless (YES, they should not necessarily be Stateless).

3. Principles.
Whenever there is the opportunity when working with SOA, people should
a. Favor Business Value exposed in the business domain OVER Business Value exposed with IT domain.
b. Favor Composability OVER Integration through Interoperability, AND favor Integration through Interoperability INSTEAD of Distribution.
c. Favor Metaphor rules INSTEAD of Tool rules
d. Favor Pure Document Style INSTEAD of RPC/RMI style. (NO WRAP TRICKS ALLOWED)
e. Favor Messaging OVER Other communication options.
f. Favor Business needs OVER specific IT practices (like optimization or flexibility)
g. Favor Entity documents OVER commanding documents
h. Favor Versionable documents OVER Structurally static documents.

So it is written.

William Martinez Pomares

Notes on SOA Manifesto

In a recent discussion at InfoQ about the news of the upcoming SOA Manifesto, I had discussion with great people, including Jean-Jacques Dubray and Steve Ross-Talbot both renowned guys in the SOA world. We all talk the same, maybe at different levels or on different realms. Still, I promised Steve to put my two cents about SOA. Well, here I have a couple of ideas about it, too high level, but trying to clarify at least the three words that conform the acronym.

Well, here they go.

1. Many people talk about SOA and Services, but I’ve found in presentations, articles, case studies, working with tools vendors and looking at real implementations, that not everyone understands the concepts quite right. So, I have a couple of posts (here, and here) and a short video in the Architecture Journal (SOA Myths), explaining the types of perceptions people have about the concepts, and why I think they are wrong. I assure you it is a good list, interesting to read. So, that would be my first contribution.
2. Now, let’s check on the Service concept. As I mention in the posts, to me a service is a cohesive (and coherent) business functionality offered through a uniform interface. And it is technologically neutral. What does that mean? Well, a service is a plain, homonymous metaphor of a business service, just like the loan service in a bank, or a delivery service of you mail office. As a metaphor, it is driven by the rules of common services, with contracts, processes, protocols, controls and evolutions. Its actual implementation may be whatever, but it should not surface the definition, meaning users of a service do not have to know how the service was implemented to use it, and should not have to learn anything else apart from the rules and protocols of regular business services interactions.
3. Now, Orientation. For an architecture, orientation describes the guidelines, principles and decisions that are based on the rules that govern the metaphor behavior. That is, the service one.
4. Architecture refers to an actual style that defines the architectural constrains, suitability and consequences of using it.
5. So, SOA is an architectural styles whose components, constrains and principles are driven by the service metaphor.
6. Service implementation is out of scope. Service metaphor implies business domain. The implementation domain should not surface into the business view, not affect the rules of the metaphor. This is something almost all of implementation fails to accomplish: to use a service you usually must know implementation details, and those are the ones that actually avoid flexibility and change.
7. The service contract requires a semantic agreement (standard shared business semantics are a must), functional specification, pre and post conditions and the description of side effects. All that is technologically neutral.
8. Lastly, and just for the records: to me, reuse is not a business concept, but an IT one. So, Services should not have as a goal the reusable property. In business, the property is composability. The key is to be able to create higher-level services from composing lower level ones. Reuse is a side effect, and should not be the base for ROI, because it will never make it!

Hope this is clear.

William Martinez Pomares

Styles, Pattern and Idioms

From a recent discussion with Duncan Cragg, related to his proposed FOREST, a get-only-rest-integration-pattern I came to think that it was good to create a little post to explain the difference between an Architecture Style and a Design Pattern. So, let’s do it.

It was Christopher Alexander, in his book A Pattern Language: Towns, Buildings, Construction. (Oxford University Press, 1977) that coined the Pattern term to denote ideas or solutions that were proven to be successful and widely used.

Well, that book was about buildings, and Alexander was an architect, of the building class. When mapped to the IT field, we have three levels at what we develop: Strategic, Tactical and Operational, or Architectural, Design, Implementation. So, we have those “ideas or solutions” in all those three levels. For Architectural level, we have Architectural Styles. For Design level, we have Design Patterns (or just plain patterns) and for Implementation level we have Idioms. You can read the definitions in POSA1 (Pattern-Oriented Software Architecture:A System of Patterns from Buschmann et al, Wiley 1996).

The style name is discussed by Roy T. Fielding in his dissertation about REST. He actually dislikes a little the name since he says it represents more a particular way of doing things (that singer’s style) rather than a general way of doing things. Coming from the art world myself, I can say it has that other meaning: a style is a way someone follows, and thus “followable”. Given someone is so original that creates a new style that others follow, does not take away that followable quality, only makes it richer.


So, as you know, the architecture of a system is the organization of its elements and their relationships, guided by principles. When defining a style, you define what types of elements would you use, what do they do, the relationships, and principles to guide their construction. A Simple example is the Client Server style. It identifies two architectural elements, the client and the server, indicates what each one does and who will the interact. Not this is a global solution: the whole system works Following this style.


BTW, Roy defines the Styles more like a set of constrains, coordinated, that define the elements and relationships. Actually, REST is defined that way in this dissertation.


When defining a Pattern, you work closer to implementation. There, you define a solution in the domain context, identifying actors and processes, relationships and results, aimed to solve a localized problem. The example here is the Factory. To solve the problem of needing different but similar objects depending on some parameter, the factory proposes the creation of the right type of object. Note this is in an object oriented context, and the solution is given in terms of objects, and it is to solve a particular problem in the whole system, not to define the whole system. Finally, note this is an idea that can be implemented in any OO language, and particularly in Java you can do it using inheritance or interfaces, meaning the pattern does not impose an specific implementation.

The Idioms are little patterns related to languages. These are proven ideas of how to accomplish things in one particular language. Say, to use StringBuffer in Java to concatenate strings.

As you can see, in general, patterns are good things, but quite different depending on the development level you are using. Now, to define a pattern, you need to provide at least five things, per Nick Rozanski and Eoin Woods, in Software Systems Architecture: Working with Stakeholders Using Viewpoints and Perspectives (Addison Wesley 2005).:

1. A name
   
2. A context where the problem and solution may be presented.
3. A problem to solve
4. The actual solution, given at the appropriate level
5. The consequences of applying that solution.

So, it is important to check all that before defining a new pattern, or before applying it. This last part is very important, since you may end up using a pattern that is not suitable for the context, for the problem or that has unwanted consequences.

Hope this helps clarify the concepts!

Talking about DSL

Originally Published on March 11th, 2008 @ 07:30:36 pm

Hey!
Back after several months!
It is incredible the amount of work a change in your job position brings in its tail!

But for now, let's talk about the title.

I was recently reading a great blog from Michael Stal (which I'm adding to the interesting blog's section). The latest post is referring to Domain Specific Languages (DSL).

It is interesting, the list of examples of what can be considered a DSL. Being as attached to formality as I’m, my take is on the D and the L of the acronym.

First, it should be Domain driven. That means this “tool” will work inside a domain scope, referring to the elements that make sense inside that domain. If used as a communicator (as I will explain later) the reader may have knowledge in that domain. For instance, if you explain your solution to a manager in terms of resources, time and cost.

The second is the language constraint. That is, DSL is a language: a grammar and a vocabulary (plus maybe rules to expand that vocabulary). The language is used to describe things in sentences. Those things could be the problem or even the solution. That description can be read, understood and even executed.

I recall a very old issue of Dr. Dobbs that talked about mini-languages (or was it micro-languages?) that were script languages in essence. An example was the MS Excel macro language of that time. Specifically, the macro language had the typical constructions for conditions and loops, but the vocabulary was focused on cells, rows and columns, selections and texts, formulas and styles. The Domain was very explicit. It also mentioned another languages, some derived from C. those where subsets of the C language with some tweaks. Were those DSLs too?

Probably no one will say C or Java is not a language, so we have the L from the DSL combo. Now, which is the Domain for a language like Java or C? Or even for those little subsets of C? I guess we can find one, very broad, but it will not fit into the idea of specifying a particular domain and focusing on it. Thus, my bet is no, they are not DSL.

Now, let’s go a little further: people use DSL all the time! I’ve known programmers everywhere that use encodings in strings. Have you done that? A string that contains a list of values separated by a “separator” (colon?) and the first value is the code of the operations, the other values means something and such? Have you hear of the interpreter pattern? Those are DLS in a String! Micro DSLs, something executable and some other time just to display.

Wait, here is another point: Does this DSL need to be executed? It may not! Actually, a language is to describe things. ADL (to describe architectures) will no be executable (probably). So they may be just to describe, to be “Human-Interpreted” languages (it may also be machine readable to validate it, but that may not be a requirement). What about a VDL (View Description Language ) that will allow the architects to describe the viewpoint of a solution in a language in the stakeholder domain ? It may be graphical, but not required. It can be a simple subset of natural language. Let’s invent the DSD (Domain Specific Dictionary) as a glossary for the DSL vocabulary.

The example that just comes to my mind is Bool’s language. It has some symbols, but when you read them is sounds like natural language, but focused on logic! A AND B OR C IMPLIES D.

Will.

Reference: Talking about DSL

WSDL 2.0 - a REST Friendly Language

Originally posted 07/20/07 @ 12:47:55 pm

W3C has published the Web Services Description Language (WSDL) Version 2.0 Recommendation. That means we can talk about a new standard now.

From history, you can recall SOAP was not a standard by committee but a de facto one, and WSDL 1.1 was a member submission done by Microsoft and IBM. Seven years later, WSDL 2.0 comes to see the light.

I mentioned before in this blog that WSDL offered four types of messaging, a combination of style/encoding parameters. There was an RPC style, and a Document Style, and for a backward compatibility, RPC could be Encoded or Literal.

Also, WSDL allowed a extension to define the transport, but it was just to say we were going to use HTTP, and that to send a SOAP structure as its payload. It was fixed to use the POST method, and it was also fixed the headers contents and such. Not much flexibility.

Well, WSDL 2.0 changes that. It now offers only one style: document. With that you can simulate your RPC calls if you want. Also, it allows to define the content of the document using an XML Schema, but that doesn't mean you will be sending XML through the wire (more on this later)!
But it doesn't stop there. WSDL 2.0 expands significantly the HTTP binding spec. Now you can specify if using GET instead of POST, indicate if you want you parameters (defined in the schema in types, remember?) to be encoded in the URL! Even, you can indicate that you want multi-part messages!

How friendly is that to REST? Keep on reading...

I know. Most of the REST community may hate anything that has to do with Web Services using its standards. But I feel that enterprise systems should not go in the wild with the REST complexity. Which complexity? you may say, if REST is the easiest thing. Well, yes and no. It is simple, but not easy. Everything has a complex component, and in REST it is the process of manually reading the contract and creating the interaction in code.

Yes, it is ok for simple parameter passing (two or three) even for some simple XML documents. But if you need to work with very complex XML and interactions, there may be a problem. Enterprise services may not be two or three parameters, and it may not be fine grained services. A way to describe all that so developers free themselves of understanding and coding XML to start thinking in business logic and processes, is a plus.

Will WSDL 2.0 that allows complex and simple things to be described, be a choice for that need of description? Who knows. What I know is that WSDL 2.0 seems to allow more Restful services descriptions, where they apply.

For more information about WSDL 2.0, please read the primer
For an article that explains Rest in WSDL 2.0 with more detail, please read this one from Eran

William Martinez Pomares.

Reference: WSDL 2.0 - a REST Friendly Language

An ORM Story

One of my students recently asked me an ORM related question . He had this little project he was working on to present in another class, and there was a little screen where he had some data. Let say he had a table with clients (relational, you may guess), and the client had a reference to the company table, since a client belongs to a company. Of course, the reference field in database was a Company ID.

His question was very simple, although very useful to explain some concepts on the spot. He was, of course, converting that client row into an object, to be later displayed in the little window. So he asked me: “Should I add a company ID attribute to the object, or should I add the company name directly?”. I looked at him and asked him back: “How do you feel by adding that ID to the object? Is it natural?” He glanced at his computer and then said… “No.”

Then we began to discuss. Actually, we started by defining what was that object’s function in the application, what was its role, what was it there for. The answer was very simple: it was there to provide info to the screen to display the data. Then, we went into discussing what the user needs, and the answer was the user needs the company name, not an ID. Lastly we went into discussing if we needed the tow objects, one Client object with a company ID and one Company object with a matching ID and a Name. We found out that, having those two objects, will require us to match them. That is a relational operation that was natural to the database. So, it was obvious we better let the database do its job and send us a new hybrid object with the client information and the company name already in place.

But wait a minute: It that ok? Weren’t we breaking the relational rules and normalization of the data? Thinking a couple of seconds I would say no. We weren’t.

Data is data, and it is stored and related in the database. You can process and produce new information by manipulating that data using the DB tools. That new information is not to store, but to consume by the business logic layers. That is BL information, it is not simple data anymore.

So the idea of ORM one-to-one does not fit in this example. If we have data and we have tools to process that and transform it into business information, then we should allow the BL layers to consume that BL info and not to spend cycles in processing, by hand, the data. Now the objects model the reality, not the data structure, and we work with cooked information and not raw data.

William Martinez Pomares.

Reference: An ORM Story

WADL, REST and WSDL

Paul kindly pointed to a blog entry about WADL use in REST, (WADL definition is found here). The Blog entry was interesting to read.

I want to quickly explain that WADL is meant to describe the possible interactions with a Web Application. Thus, it has methods, but those are HTTP commads, and it also describes the query variables (like the fields in a form) that the method needs to send to the web application. Finally, it describes the expected response.

Now, in the blog I see some misconceptions. First, it relates SOAP and WSDL to XML-RPC. That may seem true due to actual use of those two, but SOAP is just a wrapper and WSDL does not enforce XML-RPC, using document/style it reassembles a simply document sending paradigm. By the way, XML-RPC and WS used to do RPC are two completely different things.

Second, the REST based Service concept is defined to encompass even static web pages. May REST style architecture handle resources in the web, and REST “style” Services are services implemented using the REST underlying paradigm. But Static pages are not Services.

Third, WADL is at implementation level of the HTTP call, thus it does not define the service, just what to call and what to expect in response. That is not bad, it is actually good, but then WADL describes an HTTP interaction, while WSDL describes a messaging interaction. Although not actually standardized, WSDL may allow you to send messages using a message queue, SMTP, or any other transport.

Now, I want to explain my vote. I’m not a WSDL lover, I think it may be improved. Still, I’m carefull to compare, it is not as easy. We cannot say WADL is a description document for REST based Services and WSDL for RPC based ones. Right?

I may want to go even further. I may say REST Style Services may actually make use of both! Yes, while WSDL describes your Service at message level, defining the document and port, and a WADL that makes clearer the HTTP interaction (since WSDL inly indicates you are using HTTP as a transport).

Again, what do you think?

William Martinez Pomares.

Reference and other Comments: WADL, REST and WSDL

A RESTFull WSDL?

In a recent comment, Paul mentions he is not familiar with the Document Style concept. This is a great opportunity to touch the theme and clarify some ideas about WSDL and the WSA idea of a service.

WSDL is meant to describe the service definition and interaction models. WSDL defines:

• The Service’s visible endpoint. That is, the address where the port of the service leaves.
• The Binding. That is, which transport to use and how.
• The Operations. Each operation with a name and a message flow (a named message inbound or outbound).
• The Messages. Each named message has a number of named parts that conform the payload.
• The Parts. Each one is defined either by indicating the primitive type or a schema defined xml.
• The Schema. A Types section that is defined using an XML schemas.

Using the above sections, we can define the service by indicating the port, the available operations, which message flow each operation has, and what is the structure of each message.

With the WSDL, the client is able to know how to construct the message and where to send it. So far so good for our service notion.

The problem comes when WSA came out with the style/encoding idea. SOAP was originally created to access Objects remotely (Simple Object Access Protocol). Here is the story.

Those were the times when RPC was the idea of remote access. So, SOAP was created a requirement for the body of the message. It had to be constructed with a fixed structure, where the root element’s name should be the same as the method name. The children elements should be one per parameter, and each one containing the type as an attribute. That structure was known as the encoding.

When WSA brought SOAP as the protocol to form the messages, it extended the idea in two directions. The first one was to allow some flexibility by defining a non-encoding format, and that was called “literal” (as opposite of “encoded”). The other direction is the style of the access. The RPC style is the original for SOAP, where the service is accessed by mimicking an RPC by indicating the method and parameters in the message and expect a response.
The other one is the Document Style. In this style, the idea is that the message contains a document (XML usually) that is delivered to the port.

The combination of style and encoding gives us four possibilities: RPC/Encoded (original RPC/SOAP style), RPC/Literal (A new RPC that is not that strict, see below), Document/Encoded (Nonsense), and Document/Literal (what all of us should use).

Now, let’s focus in RPC/Literal and Document/Literal. When defining the operations, the developer is able to indicate, per message, which style and encoding to use. If RPC/Literal is selected, the following rules apply:

• The body of the message is an XML with a root element whose name is the name of the operation.
• The children of that root element are the parameters, in order, for the implementing method.

A client calling a service’s operation defined as RPC/Literal, should create a message then that reassembles the structure of an RPC SOAP Message. The important thing here is that the XML in the body is created automatically with a root that has the operation name.

If Document/Literal is selected, the following rules apply.

• The body of the message is an XML document. No other restriction is given.

Note that with document/literal, there is no restriction of the body format. If by chance the root of that XML is not the name of the operation, it doesn’t matter. In reality, some of the vendors I tested, even if document style is indicated, will look for the name of the method to call in the first element of the body.

So, now imagine a service at port http://willyloans .com, that uses http, that has an operation called LoanRequest with one inbound message. That message is a one-part message, document style. That part is an XML document defined in the schema at Types section. The client should simply create a SOAP wrapper XML, and in the body element it will add the XML document (Payload). The client then simply sends that SOAP to the address defined in service (always using a post, WSA defined that).

That’s it. Using WSDL at document style, you can interact with the service just by sending a message containing a document, delivered to a port. NO method names nor parameters. That should be a RestFull call as Paul indicates, but with the help of WSDL that describes the flow, port and the XML document schema.

Hope this explanation helps.

William Martinez.

Reference and Comments: A RESTFull WSDL?

A REAL service definition

Based on several comments and articles I've read, I tend to think that SOA and Web Services are being misunderstood. Maybe I’m the one that is wrong, but just in case I will try to explain here what I understand. I guess the first thing to do is to define what a service is.

Base on the Web Service Architecture specification, a service is “… an abstract resource that represents a capability of performing tasks that represents a coherent functionality from the point of view of provider entities and requester entities.”

I want to point out the fact that a service is a “resource”, it can perform some tasks, and it represents functionality. A service has an ID that will let us find it in the networking cloud. It has a description and it has an interface. That interface “… is the abstract boundary that a service exposes. It defines the types of messages and the message exchange patterns that are involved in interacting with the service, together with any conditions implied by those messages.”

Let’s put it in other words. A Service is a coherent functionality offered by a web resource. To communicate with it, you use its interface. It will accept messages interchanged in a predefined pattern.

But there is an important fact: “To be used, a service must be realized by a concrete provider agent.”, WSA spec says. In other words, a service is an abstract model of a resource. That functionality is to be realized by a concrete agent, may it be software or hardware. Let think of it as a functional cloud, accessed by messages delivered to a port.

An Example may help.

Service: Loan service.

Functionality: Actually, the service is able to process loan requests, payments, notifies due loans and you can ask for a loan status.

How is it done?: There are four document types, each one has a particular schema: LoanRequest (input), LoanInfoRequest(input/output), LoanNotification (output) and LoanPaymentNote(input). Any input XML document may be sent to a port located in www.willyloans.com/loanport or to the email loanport at willyloans.com. There, an XML processor will determine the schema type, and send the actual data to the loan analysis department, to the loan payments subsystem, or to the loan service desk system. You can guess what each system does, and what each document may contain.
You can create four WSDL if you want. All pointing to the same address. Just make them document style.

Note that the service doesn’t reassemble an object. It has no methods or attributes, just functionality. You don’t call it (although pure objects are supposed to receive messages), and they may not have a response (although they can send a message back, or the same modified message).

Mainstream is actually building web services from the actual implementation. Instead of creating a service that is realized using exiting classes and systems, developers are simply exposing their methods and objects. They are using an RPC model instead of messaging. They are architecturing a distributed object system instead of services.
This leads to several myths and perceptions that make tool vendors offer what developers want, and none is working towards a truly service development.

I will check on those myths in future posts.

William Martinez Pomares

Reference and other comments: A REAL service definition

YAMTCARO and the Service apology

I just wrote an answer in TSS that I thought I could share here too. The basic idea everyone has about services is that they are to distribute logic, make remote calls, have loose coupling interfaces, and are resusable. And nothing is working as it is advertised. I will play the defendant part here.

“I see a repeating idea about SOA, services in particular, that doesn’t fit in what I have learned from my childhood as an architect. I will explain myself.

I recall the old Object oriented days when all the fuzz was about reusability. The idea was clear: separate the code into coherent and functional complete things. Then a problem was found: the interface. You could not reuse the thing because of the interface not being suitable, or requiring things not in the new problem domain.

Then a service came. It was the idea of having a business functionality (not an interface, not an object) able to accept messages and offer a business value. It has no reusability concept, the fuzz was actually about replacing fixed interfaces with a simple port. And somebody said: Let’s implement it with SOAP. And SOAP was Simple Object Access Protocol, an RPC oriented wrapping protocol used to access distributed objects. Wow. Wait a minute. Something is not working here. I know objects were supposed to accept messages. Nobody uses that. But a service is not an object. A service has no methods or parameters. Definitively, it has no response. There is no interface per se, just a port where you deliver your message.

Now, the message is not SOAP. SOAP is a wrapper. The real thing is in the body.

Once the service has read from the port the message content, it will now know what to do. And it may decide to send another message. As simple as that. But as difficult to grasp for an object programmer, that it was reduced to a YAMTCARO (Yet another method to call a remote object).

NOw, can somebody tell me why a service needs a method name to be called? SOAP had stubs in the client, to simulate the remote object as local. Services are not object, stubs have no place here. Makes no sense. You need a port object to stream your message. Simple.

Finally, since a service is just a port, and the service semantics (which are not technically describable) is hidden behind the service cloud. You can create a versioning system underneath the cloud, so old messages can still be accepted and new messages, that represent new business needs, be processed as required. Service cloud still as white as before. It may have a new port, but old ports may be still there.

Enterprise architects? Their job is to have one eye in the problem space, and the other in the solution space. They will work with business people to design services scope (business driven), and work with designers to technically create the structure of the cloud.

Hope this helps to understand why I say all that I say.”

William Martinez Pomares

SOA in all sizes

Funny article in SOA Masters Class site. It explains the vision of SOA based in two variables: the Architecture involvement scope, and the Service concept scope.
Yep, there is a big difference when you see the Service concept as an exposed component, or as business functionality. Same for involving the architecture simply as a glue to interoperate disparate systems, or as a business driven structure.

Funny indeed!

William Martinez Pomares

First Post, an SOA discussion!

Hi All!

Very excited that I’m writing my very first post in the blog.
And since this is an Architecting blog, I thought I could point it to a very interesting discussion held at The Server Side.

The article presented here is about the complexity generated when using SOA, compared to the same complexity history of CORBA times. Although the idea is nice, most of the participants show a problem of understanding what SOA really is.

System Integrator Technology? CORBA with a new acronym? A new distributed approach to organize business logic? Simple EJB, SOAP and other technologies follow up, with nothing new? No several times.

As I mentioned in my responses there, SOA is based on the service Metaphor, which is placed in the problem domain, problem space, where business organization rules and not technology trends. SOA now is a patched, almost like a stovepipe architecture, solution for integration, and like that it sells.

Later I will write a little bit more about the Service metaphor. That is not for RPC developers, I’m sure.

William Martinez Pomares