O V E R V I E W

Using SOAP to access ArcGIS Server Web Services
 

ArcGIS Server SOAP Web services rest on two standard XML-based W3C specifications: WSDL (Web Service Description Language) and  
SOAP.  

WSDL is a specification used to describe networked XML-based services.   In general, WSDL provides a simple way for service providers to describe the basic format of requests to their services, regardless of the underlying protocol.   One of those protocols, and by far the most popular, is SOAP.  SOAP is used to describe the format of a message sent to a networked service and allow computers to communicate independently of an operating system or platform.   SOAP messages can be transmitted to a service via a number of transport protocols, including HTTP.

Consuming SOAP Services

Developer environments, such as .NET or Java, provide SOAP toolkits to automate the process of generating a set of local, native classes for a consumer.  The WSDL provides the client all it needs to generate the native proxy and value objects, thus no proprietary components related to the Web service are necessary.
 

Value objects are simply objects that store values or properties.   Depending on the WSDL, there can be many different types of value objects.   On the other hand, there is only one proxy class per SOAP service type.  The proxy has both properties and methods.  The methods are designed to create and submit a SOAP request and return a SOAP response.   The proxy uses the value objects to construct (serialize) a SOAP request.  The proxy also deserializes the SOAP response and constructs value objects to be used by the client.  So working with a rich client object environment makes it much easier to consume and utilize a SOAP service because you are using native objects to store properties (value objects) and manage SOAP requests and responses (proxy) on the client.
 

Consuming ArcGIS Server Web Services

A WSDL is used to generate the proxy classes and value objects for each ArcGIS Server service type. There is one WSDL and thus one SOAP proxy class for each service type.  The capabilities of an ArcGIS Server SOAP Web services are defined by the methods of the proxy.   The proxy is designed to work with ArcGIS Server services in a stateless manner, thus the proxy class provides methods to initiate stateless requests to an ArcGIS Server service and return results.   The ArcGIS Server SOAP proxy uses value objects when calling a method and returning results.   SOAP proxies and value objects are usually generated by a SOAP toolkit designed for a specific development environment such as .NET and Java.   For example, Visual Studio 2005 contains an integrated SOAP toolkit (wsdl.exe) for .NET developers and the Java community maintains a number of options such as Apache Axis.  It is important to note that no ESRI components need to be installed or available on the client.  Thus a client application can utilize ArcGIS Server Web services much like any other SOAP-based Web service.

ArcGIS Server SOAP Web services use the following url pattern:  

http://<Web Server Hostname>/<ArcGIS Instance>/services/<FolderName>/<ServiceName>/<ServiceType>

<Web Server Hostname> is the hostname of the Web server on which the ArcGIS Server Web services application is deployed.

<ArcGIS Instance> is the name of the virtual directory in which the Web "services" are made available.  Each instance is associated with one ArcGIS Server SOM (Server Object Manager).

<FolderName> is the name of a virtual folder on the ArcGIS Server.  One or more services may reside within a folder.   Exposing services in a folder is optional.   If a service is not in a folder (it is exposed at the root), the FolderName portion of the url is omitted.  See the Catalog proxy's GetFolders method to determine if an ArcGIS Server site has folders.   
 

<ServiceName> is the name of the ArcGIS Server service.

<ServiceType> is the service or service extension type.  This type must provide a WSDL to be utilized via SOAP.  Valid service types are listed in the table below.

The WSDL for a service or extension will provide the necessary information to determine how to interact, via SOAP, with the Web service.  The WSDL can be returned by adding "?wsdl" to the url.


ArcGIS Server Web Service proxies and value objects

The proxy and value objects for an ArcGIS Server service only need to be generated once per service type.  Once the Web service proxy and value objects for an ArcGIS Server service have been created, they can be reused with other ArcGIS Server Web services of the same type, even though the proxy class name contains the original service name (dynamic proxies only).   For example, if a Web service proxy class is generated dynamically using a map service named "NorthAmerica", the proxy class name will be "NorthAmerica_MapServer".  The default endpoint for the MapServer proxy will be associated with the NorthAmerica map service.  To use another ArcGIS Server Web map service named "Europe", set the Url property to define the Web service endpoint to the "Europe" ArcGIS Server Web map service.  The same applies for all ArcGIS Server service types.  A comprehensive list of service types and descriptions is provided below.