Web-Services Overview

http://tutorials.jenkov.com/web-services/overview.html

Web services are services that can be accessed over a network, for instance via the global internet. Often these web services and their clients communicate via web protocols like HTTP.

 The term "web service" is often used to describe a service that a client (a computer) can call remotely over the internet, via web protocols like HTTP. Like calling a method, procedure or function which is running on a different machine than the client. As such web services are very similar to "remote procedure call" (or just "remoting") protocols, like Java's RMI, Windows DCOM, Corba's IIOP etc. The basic web service principle is illustrated here:

A web service accessed via internet by a client

                       A computerized client calling a web service over the internet.

Web services can also be used internally in an organizations network, as a way to allow many different applications to interact with each othWeb Services vs. Websites / Web Applicationser. The standardized web service protocols then makes it easier to integrate the various applications. This principle is illustrated here:

 Web Services vs. Websites / Web Applications

The main difference between a web service and a web site is, that a web site is typically intended for human consumption (human-to-computer interaction), whereas web services are typically intended for computer-to-computer interaction.

Of course this distinction is somewhat blurred. A web application can contain both a graphical user interface for human users, as well as a set of web services for computer "users" (clients). For instance, a payment service like Paypal has both a graphical user interface for human users, as well as a set of web services through which you can have your own backend systems access the Paypal services.

This illustration shows a web application that contains both a graphical user interface, and a web service interface (a set of web services exposing selected functions of the web application):

A web application with a GUI for human users, and web services for computerized clients.

Web Service Message Exchange Patterns

There are multiple types of web services. Some web services a client calls to obtain some information. For instance, a client may call a weather web service to read weather information. These are typical read-only web services. A read-only web service may in practice send an empty request to the web service, which then sends the data back. So, even if a web service is read-only, the client might actually have to send some data (a minimal request) to the web service to obtain the data it wants to read.

Other web services are more write-only kind of web services. For instance, you may transfer data to a web service at regular intervals.

And then others are read-write services where it makes sense to both send data to the web service, and receive data back again.

All three communication patterns are illustrated here:

Web services as both read-only, write-only and read-write services.

Three message exchange patterns of web services: Read-only, Write-only and Read / Write .

Three message exchange patterns of web services: Read-only, Write-only and Read / Write .

Web Service Message Formats

   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 HTTPWeb Service Interfaces/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>

Web Service Interfaces

If a web service is to be "callable" for clients from the outside world, the client need a description of the service    SOAP

    REST + XML

    REST + JSON

    XML RPC interface. Without a description of the interface, how would the client know what data to send to the service?

You can think of a service interface like an interface in Java or C#. The only extra information needed is where the service is located (IP address), and the message format used by the service. Here is what a service description should contain:

    Interface Name

    Operation Name(s) (if the service has more than one operation).

    Operation Input Parameters

    Operation Return Values

    Service Message Format

    Service Location (IP Address / URL)

How a web service interface description looks depends on the message format used by the web service. Currently, only SOAP web services has a standardized interface description - the Web Service Description Language (WSDL). WSDL will be described in its own trail later.