A Retrospective Look At Web Services

A Retrospective Look At Web Services

After a considerable break from reading about the web services technology, I once again visited the subject with a view to look at it retrospectively.

1.1 SOAP Web Services

SOAP Web Services is the original style of web services. It started with a specification about the web service: the WSDL file. This file had the same function as an IDL file had in the days of COM. And not surprisingly, because the SOAP web services have evolved from component technologies like COM and CORBA. So, the WSDL file defines the contract between the client of the web service and the web service itself.

In order to make the web service independent of the programming languages and their types, and also of the network transport, the WSDL became a detailed specification based on XML Schema that defined the data types, the operations and their parameters and the bindings.

The advantage of the detailed specification of the contract was that it allowed the client and even the web service to be written independently. That is, given the WSDL, a developer could write the web service to adhere to the WSDL spec and another developer could write the client to such a web service.

1.2 A C++ Example

Eventually what happened was that Soap Toolkits became available that could read a WSDL specification and generate the client side and server side code. For example, I had once a need to invoke a SOAP web service from a C++ program and there wasn't any standard IDE option to do this automagically. Therefore, I looked for and found a SOAP toolkit library called gsoap that would generate C++ code when it was supplied with a WSDL file.

For the client side, the gsoap library generates a set of files that contain the methods on the web service. These methods act like proxies to the client program. Internally, the generated code converts the parameters to the method calls to the appropriate request xml and make the call over the network to the web service. Consequently, from my source code, I could make the call to the web method in the generated code and the actual call to the web service would be made under the covers, so to speak.

For the web service side too, the gsoap library would generate a set of files that contain the methods of the web service. This code needs to be invoked by a transport handler like IIS or Apache web server. Once the call is passed on to the generated code, it converts the request xml into parameters and invokes a method in your code.

1.3 Microsoft .NET and Java

With MS .NET, it became trivial to write SOAP web services since the IDE took care of practically everything. All you needed to do was to select a Web Service project and annotate the web method with [WebMethod] and the IDE did everything else.

What was happening behind the scenes is that the IDE generated the WSDL for the web service and it generated the code to translate the request xml into parameters (much like in the C++ case) and at run time, it would make the appropriate call to the web method. And the response xml would be generated similarly.

On the Java side, there were frameworks like Axis from Apache that did much the same thing for java programs that MS .NET did for C# programs.

1.4 XML Requests and Responses

With the SOAP specification, there was a great amount of detail involved in generating the xml for the request and response for a web service method. There were four possible variations:
RPC / encoded
RPC / literal
Document / encoded (never used)
Document / literal

What these variations mean is that the xml generated for the request and response is different. The choice of which xml variation is used is what the WSDL specifies. In general, it doesn't matter much which variation is used. From the programmer's point of view, it doesn't matter at all because the SOAP toolkit deals with the details. From the point of view of performance or other such consideration also, the difference isn't great. After all, it is a few more or less characters to be transmitted. 

A toolkit like SoapUI will generate the correct request xml structure for any given WSDL taking care of the xml variation specified.

2. REST Web Services

On looking at all the infrastructure required to create SOAP web services, it became clear that a lot of it was quite unnecessary. What SOAP web services were providing is the ability for the programmer to write web services and their clients in terms of native data types. The infrastructure took care of converting the data from raw xml on the wire to native data types.

However, there was no good reason for this. Programmers had good libraries at hand to read the data in the xml themselves. So, what emerged is the practice of clients building the request xml in the code and parsing the response xml using DOM or SAX parsers. And likewise on the web service side.

In order to bring some kind of uniformity to this practice, a few standard mechanisms were proposed for the requests in terms of the common database operations:
C - create: http POST request
R - read and list: http GET request
U - update: http PUT request
D - delete: http DELETE request

This standardized use of the different HTTP verbs for different operations is referred to as the REST protocol for web services.

Basically, what was changed was two things: (1) the practice of xml being created and interpreted in the code of the web method itself instead of relying on an infrastructure to convert xml to native data types, (2) the call to the web method being made from the client directly using a library that allows making a TCP/IP call instead of letting the infrastructure do it behind the scenes.

3. Conclusion

What a lot of web service implementations do today is to use the practice of REST web services without the use of the REST convention. For example, they may use only the POST method for all the operations supported by the web service. We refer to such web services as REST-style web services.

The shift from SOAP to REST style web services has simplified the development process by removing all the "under the hood" kind of processing and making xml exchange explicit between the client and the web service.

Html, JavaScript and CSS- the Big Picture

For the last several years, the nature of software has changed from a write-everything-yourself to a write-the-glue kind of approach. Most of the time we write code nowadays, we are using a lot of third-party code to achieve our software ends. Examples are java libraries (or .net libraries) or even javascript libraries and html frameworks.

What is quite forbidding to anyone approaching the subject for the first time is the plethora of systems and conventions and interfaces that face the newcomer. What is needed at such a time is to cut to the chase and get at the core issues. That's easier said than done. The reason is that there are multiple facets to any new technology and without seeing the whole picture, you can never really come to grips with the subject.
Here is an attempt at giving a whole-picture view of the subject of Html, Javascript and CSS. To do this, I am taking the example of an Javascript calendar. So here goes.
The way to approach this subject (or any new technology) is to try to create a big-picture view in your own mind. What is a Javascript calendar at the implementation level? To answer this, we need to consider the following facets of the calendar:

1. What is the structure of the html that hosts the calendar?
2. How is the calendar shown and hidden?
3. How is the content of the calendar (the dates) painted?
4. How does the calendar provide the date back to the html form?

If we have an answer to each of these questions, we will have a big-picture view of the whole problem.

1. What is the structure of the html that hosts the calendar?
The html structure for the calendar will be a <table> having a <tbody> that represents the dates in the calendar. And a text input that will hold the result of a date selection from the calendar.

This means that the html structure will be something like the following:
    <html>

    ...

    <body>

    ...

    <form>

    <!-- textbox showing date -->

    <input type="text" id="txtDateField" /> 

    </form>

    <table id="tblCalendar" >

     ...

    <tbody id="tbdDates" />

    </table>

     ...

    </body>

    </html>

2. How is the calendar shown and hidden?
The calendar will be shown and hidden using javascript. The javascript construct

    object.style.display 

can be assigned the value "none" to hide the object
and it can be assigned the value "block" to display a block element.

We use this mechanism in the javascript code:

    function hideCalendar()

    {

        var cal = document.getElementById("tblCalendar");

        cal.style.display = none;

    }

3. How is the content of the calendar (the dates) painted?
This is the more complex part of the implementation. The dates in the calendar need to be constructed in javascript because the contents of the table cells are dependent on the month and year selected.

To create the contents of a table, we need to construct the elements of the dom and attach the structure to the tbody element. We need to create a row <TR> element. And within it, we need to construct data <TD>elements. And finally attach the row to the tbody element. All this can be achieved in javascript:

    ...

    tblDates = document.getElementById ( "tbdDates" );

    tr = document.createElement ( "TR" );
    for (...)
    {
        td = document.createElement ( "TD" );
        td.appendChild ( document.createTextNode(dt++) );
        tr.appendChild ( td );
    }   
    tblDates.appendChild(tr);
    ...

4. How does the calendar provide the date back to the html form?
For each of the td elements, we need to add an onClick member that invokes a function. The parameters to the function are the year, month and date values. This part of the code is advanced javascript. It looks as follows:

    var str = d + "-" + month + "-" + year;
    td.onclick = new Function ( "document.getElementById('txtDateField').value='" + str + "'" );

This code constructs a function object for each td element in the dom. The function object is compiled when the button is clicked and executed. The code that gets executed is:
    document.getElementById('txtDateField').value='12-6-2012'
which sets the contents of the form element representing the date.

Conclusion

I have not provided the complete code for the javascript calendar here. The reason is that the purpose of this article is to show the central facets of a html-javascript interaction. It tries to answer the question "how does one go about writing a javascript based web page?". And the answer is that you have to first frame the right questions and then answer each one of them. The answers should give you a big picture view of the problem and its solution. Once that is achieved, the implementation is almost trivial.

In this case, start with the html above and put it in a cal.htm file. Add a <script> tag and add the javascript function to hide and show the calendar. In the table tag add another tbody with some static content. Use this as a starting point to implement the show / hide functionality. Once this is running, add the table contents with some static dates. Integrate the code to invoke the integration with the text date field. Proceed to add embellishments to select months and years. Add CSS styles to make the calendar look more slick. And your javascript calendar comes to life before your eyes.