Adobe ColdFusion 8

Web services

Since its inception, the Internet has allowed people to access content stored on remote computers. This content can be static, such as a document represented by an HTML file, or dynamic, such as content returned from a ColdFusion page or CGI script.

Web services let you access application functionality that someone created and made available on a remote computer. With a web service, you can make a request to the remote application to perform an action.

For example, you can request a stock quote, pass a text string to be translated, or request information from a product catalog. The advantage of web services is that you do not have to recreate application logic that someone else has already created and, therefore, you can build your applications faster.

Referencing a remote web service within your ColdFusion application is called consuming web services. Since web services adhere to a standard interface regardless of implementation technology, you can consume a web service implemented as part of a ColdFusion application, or as part of a .NET or Java application.

You can also create your own web services and make them available to others for remote access, called publishing web service. Applications that consume your web service can be implemented in ColdFusion or by any application that recognizes the web service standard.

Accessing a web service

In its simplest form, an access to a web service is similar to a function call. Instead of the function call referencing a library on your computer, it references remote functionality over the Internet.

One feature of web services is that they are self-describing. That means a person who makes a web service available also publishes a description of the API to the web service as a Web Services Description Language (WSDL) file.

A WSDL file is an XML-formatted document that includes information about the web service, including the following information:

  • Operations that you can call on the web service
  • Input parameters that you pass to each operation
  • Return values from an operation

Consuming web services typically is a two-step process:

  1. Parse the WSDL file of the web service to determine its interface.

    A web service makes its associated WSDL file available over the Internet. You must know the URL of the WSDL file defining the service. For example, you can access the WSDL file for the TemperatureService web service at the following URL:

    www.xmethods.net/sd/2001/TemperatureService.wsdl

    For an overview of WSDL syntax, see Working with WSDL files.

  2. Make a request to the web service.

    The following example invokes an operation on the Temperature web service to retrieve the temperature in zip code 55987:

    <cfinvoke 
      webservice="http://www.xmethods.net/sd/2001/TemperatureService.wsdl"
      method="getTemp"
      returnvariable="aTemp">
        <cfinvokeargument name="zipcode" value="55987"/>
    </cfinvoke>
    <cfoutput>The temperature at zip code 55987 is #aTemp#</cfoutput>
    

    For more information on consuming web services, see Consuming web services.

Basic web service concepts

You must be familiar with the underlying architecture of a web service provider in order to fully understand how web services work.

Note: This section contains an overview of the architecture of web services. For detailed information, consult one of the many web services books.

The following are three primary components of the web services platform:

  • SOAP (Simple Object Access Protocol)
  • WSDL (Web Services Description Language)
  • UDDI (Universal Description, Discovery, and Integration)

The following simple image shows how the ColdFusion implementation of web services work:

The following sections describe the components shown in this image.

Supporting web services with SOAP

SOAP provides a standard XML structure for sending and receiving web service requests and responses over the Internet. Usually you send SOAP messages using HTTP, but you also can send them using SMTP and other protocols. ColdFusion integrates the Apache Axis SOAP engine to support web services.

The ColdFusion Web Services Engine performs the underlying functionality to support web services, including generating WSDL files for web services that you create. In ColdFusion, to consume or publish web services does not require you to be familiar with SOAP or to perform any SOAP operations.

You can find additional information about SOAP in the W3C's SOAP 1.1 note at www.w3.org/TR/SOAP/.

Describing web services with WSDL

A WSDL document is an XML file that describes a web service's purpose, where it is located, and how to access it. The WSDL document describes the operations that you can invoke and their associated data types.

ColdFusion can generate a WSDL document from a web service, and you can publish the WSDL document at a URL to provide information to potential clients. For more information, see Working with WSDL files.

Finding web services with UDDI

As a consumer of web services, you want to know what web services are available. As a publisher of web services, you want others to be able to find information about your web services. Universal Description, Discovery and Integration (UDDI) provides a way for web service clients to dynamically locate web services that provide specific capabilities. You use a UDDI query to find service providers. A UDDI response contains information, such as business contact information, business category, and technical details, about how to invoke a web service.

Although ColdFusion does not directly support UDDI, you can manually register or find a web service using a public UDDI registry, such as the IBM UDDI Business Registry at https://www-3.ibm.com/services/uddi/protect/registry.html.

You can find additional information about UDDI at www.uddi.org/about.htm.