1. Web Services
2. Web Services Overview
3. Web Service Message Formats
4. Web Service Interfaces

• SOAP
• REST + XML
• REST + JSON
• XML RPC

When a client and a web service communicate they exchange messages. A request message is sent from the client to the web service. The web service responds with a response message. This is just like in ordinary HTTP, where a web browser sends an HTTP request to a web server, and the web server replies with an HTTP response.

In the beginning the only web service message format available was SOAP. Later came REST type web services, which uses plain XML and HTTP. Following the REST movement came a wave of people using JSON (JavaScript Object Notation) as message format. Another very simple remoting protocol is called XML-RPC (XML Remote Procedure Call). Of these, the most common is SOAP and I will not get into details with these message formats here, since they will get their own tutorial trails later. I will just briefly mention what they look like.

A clients sends a request message to a web service, and receives a response message.

SOAP

SOAP (Simple Object Access Protocol) is an XML based message format. Here is a simple SOAP message:

<?xml version="1.0"?>
<soap:Envelope
xmlns:soap="http://www.w3.org/2001/12/soap-envelope"
soap:encodingStyle="http://www.w3.org/2001/12/soap-encoding">

    <soap:Header>
    </soap:Header>

    <soap:Body>

        ... message data ...

        <soap:Fault>
        </soap:Fault>

    </soap:Body>

</soap:Envelope>

As you can see a SOAP message consists of:

• Envelope
  • Header
  • Body
    • Message Data
    • Fault (optional)

The same SOAP message structure is used to send both requests and responses between client and web service.

The Fault element inside the Body element is optional. A Fault element is only sent back if an error occurs inside the web service. Otherwise the normal message data is sent back.

SOAP doesn't specify how a message gets from the client to the web service, although the most common scenario is via HTTP.

REST + XML

REST (REpresentational State Transfer) style web services work a bit different from SOAP web services. A REST request is a simple HTTP request just like a regular browser would send to a web server. There is typically no XML request sent. A REST response is typically an XML document sent back in a regular HTTP response, just as if a browser had requested it.

In REST you don't think so much in terms of "services", but rather in "resources". A resource has a given URL, just like an HTML page in a web site. An example of a resource could be a user profile in a social application. Such a resource could have the URL:

http://social.jenkov.com/profiles/jakobjenkov

This URL might return an XML document (resource) describing me. Here is how the XML file returned could look:

<profile>
    <firstName>Jakob</firstName>
    <lastName>Jenkov</lastName>
    <address>
        <street>The Road 123</street>
        <zip>12345</zip>
        <city>Copenhagen</city>
    </address>
</profile>

REST also naturally supports collections of resources. For instance, this URL might represent a list of all public user profiles:

http://social.jenkov.com/profiles/

Here is an example of how such a profile list in XML could look:

<profiles>
    <profile>...</profile>
    <profile>...</profile>
    <profile>...</profile>
</profiles>

The two URL's above only reads a resource or resource collection. If you need to modify a resource in REST, you do so by sending different HTTP request to the server. When you read a resource you send an HTTP GET request. If you need to write a resource, you would send an HTTP PUT instead. If you need to delete a resource you would send an HTTP DELETE etc.

REST + JSON

REST + JSON is basically the same as REST + XML except that data is transfered in JSON (JavaScript Object Notation) instead of XML. The advantage of JSON over XML is that web browser are able to parse the JSON structures into JavaScript objects natively. You don't have to parse the JSON yourself in the browser then. That is much easier to work with in applications that use AJAX a lot.

Here is a JSON example:

{
    firstName : "Jakob",
    lastName  : "Jenkov",
    address   : {
       street : "The Road 123",
       zip    : "12345",
       city   : "Copenhagen"
    }
}

XML RPC

XML RPC is closer to SOAP than it is to REST. XML RPC has both a request and a response format. XML RPC is a somewhat simpler protocol than SOAP is. It is also closer modeled to a regular procedure call. Some people claim that XML RPC is now dead or obsolete.

Here is a simple XML RPC request example:

POST /RPC2 HTTP/1.0
User-Agent: My XML-RPC API/1.0.0 (Win7)
Host: jenkov.com
Content-Type: text/xml
Content-length: 200

<?xml version="1.0"?>
<methodCall>
    <methodName>getProfile</methodName>
    <params>
        <param>
            <value><string>Jakob Jenkov</string></value>
        </param>
    </params>
</methodCall>

Note: The Content-Length HTTP header is not set correctly. It should contain the number of bytes in the XML request.

Here is an XML RPC response example:

HTTP/1.1 200 OK
Connection: close
Content-Length: 213
Content-Type: text/xml
Date: Wed, 03 Feb 2010 20:00:00 GMT+1
Server: jenkov.com
    
<?xml version="1.0"?>
<methodResponse>
    <params>
        <param>
            <struct>
                <member>
                    <name>firstName</name>
                    <value>Jakob</value>
                </member>
                <member>
                    <name>lastName</name>
                    <value>Jenkov</value>
                </member>
                <member>
                    <name>address</name>
                    <value>
                        <struct>...</struct>
                    </value>
                </member>
            </struct>
        </param>
    </params> 
</methodResponse>