ArcGIS Server SOAP API Overview

The ArcGIS Server SOAP API is an XML-structured language for communicating with ArcGIS Server services based on the SOAP standard. Server objects and some server object extensions have a defined set of SOAP elements and attibutes, known as a schema, they can utilize to process SOAP requests and generate SOAP responses. Since this capability is enabled at the server object level, as a developer you can interact with a server object using SOAP without using a Web service. ArcGIS Server Web services expose this capability via a Web service endpoint, but the SOAP request and response are still handled by the server object or server object extension directly. The easiest way to work with the SOAP API is to use a SOAP toolkit to generate SOAP proxies and value objects in the native development environment. Instead of managing SOAP strings directly, you can use the native proxy and value objects to work with ArcGIS Server services via a Web service endpoint or via the SOM.

The SOAP API is designed to make stateless use of ArcGIS Server services.  As a result, methods on the stateless ArcObjects interfaces implemented by a server object or extension mirror the methods on a SOAP proxy.   For example, both the MapServer SOAP proxy and the IMapServer ArcObjects COM interface expose the ExportMapImage method.    While the protocol and types are different, the usage is generally the same.  A call to the ExportMapImage method generates a new map image without inherently storing or changing the state of the map server object.  A list of the complimentary SOAP proxy and ArcObjects COM interfaces are provided in the ArcGIS Server Web Services Implementation section below. 

ArcGIS Server Connections

ArcGIS Server services can be made accessible via Local and Internet connections.   Local connections are established by using ArcObjects within a client application to connect to the Server Object Manager (SOM).  Internet connections are established by using native objects within a client application to connect to a Web service endpoint.   "Native object" means an object managed solely in the native development environment, like .NET or Java.  Local connections offer the ability to work with services, namely server objects and server context, using the ArcObjects API and the SOAP API.    Stateful changes to a service (server object) can only be made using the ArcObjects API and thus require a local connection.  Internet connections only offer the ability to work with services using the SOAP API, so all service interaction is stateless.   In general, ArcGIS Server connections in client applications can be summarized as follows:

• Internet connections always use the SOAP API and define a connection using a url to a Web service endpoint.   Internet connections can be used by both internal (LAN) and external (Internet) clients. 
• Local connections always use the ArcObjects API and may use the SOAP API, depending on the client application.  Connections are defined using the name of the SOM machine with optional identity credentials.  Local connections can only be used by internal (LAN) clients.

Both connection types can be used to consume ArcGIS Server serivce in pre-created, rich application clients such as ArcMap, ArcCatalog, and ArcGIS Explorer.  The Web ADF and ArcGIS Server Manager also enable the use of ArcGIS Server services without explicitly defining which API you're using.  The API becomes important for application developers to determine the capabilities and limits when working with ArcGIS Server services.  As a result, working with the SOAP API will require developer level skill and knowledge for a number of Web service standards and specifications, in addition to ArcGIS Server service capabilities.            

Web Service Standards

The ArcGIS Server SOAP API rests on two standard XML-based specifications: WSDL - Web Service Description Language and SOAP - Simple Object Access Protocol.  WSDL is a specification used to describe networked XML-based services.   Although the term "Web Service" is part of the moniker, WSDL is not restricted to traditional HTTP-based Web 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.   SOAP messages can be transmitted to a service via a number of transport protocols, including HTTP and DCOM (distributed COM).      

ArcGIS Server SOAP Implementation

SOAP support for server objects and server object extensions is defined at the ArcObjects level.  So at some point in the communication cycle, ArcObjects must be used.  Two basic ArcObjects interfaces are used to interact with the SOAP API: IServiceCatalogAdmin and IRequestHandler.  Updated versions of both interfaces are available, for example IServiceCatalogAdmin2 and IRequestHandler2.   IServiceCatalogAdmin is used to get a WSDL for server objects, server object extensions and ServiceCatalog.  ServiceCatalog is a well-known service managed internally by the SOM and used to get a list of services and their properties from an ArcGIS Server site using the SOAP API.  IRequestHandler is used to process SOAP requests and generate SOAP responses.  Interaction with an ArcGIS Server service via the SOAP API rests on the implementation and use of the IRequestHandler interface.   The following ArcGIS Server services and extensions provide a WSDL and implement the IRequestHandler interface, thus they can be utilized via the SOAP API:

WSDLs

The Server Object Manager (SOM) is responsible for providing the WSDL for a service type to a client.  The WSDL for each supported service type is stored in the <ArcGIS Install>\XMLSchema folder using the server type name with the file extension ".wsdl".   The content for each WSDL is provided via the links below:

• ServiceCatalog
• MapServer
• GeocodeServer
• GPServer
• GeoDataServer
• GlobeServer
• NAServer

Using the ArcObjects API and the IServiceCatalogAdmin interface on the ServiceCatalog object, you can get access to the WSDL for each service type.  The ServiceCatalog (Catalog) WSDL is returned by the GetCatalogDescriptionDocument() method and each service type (e.g. MapServer, GeocodeServer) WSDL is returned by the GetDescriptionDocument() method.   The byte array returned from either method contains the WSDL document referenced by the links above.  The IServiceCatalogAdmin interface is included in the ESRI.ArcGIS.Server.dll. 

[C#]

ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection gisconnection =
  new ESRI.ArcGIS.ADF.Connection.AGS.AGSServerConnection();
gisconnection.Host = servername;
gisconnection.Connect();

IServerObjectManager serverManager = gisconnection.ServerObjectManager;
IServerContext serverContext = serverManager.CreateServerContext(servicename, servertype);

IServiceCatalogAdmin2 isc = (IServiceCatalogAdmin2)serverContext.CreateObject("esriServer.ServiceCatalog");

UTF8Encoding utf8 = new UTF8Encoding();

// Catalog WSDL
byte[] bitscatalog = isc.GetCatalogDescriptionDocument("Catalog", "http://localhost");
string catalog_wsdl = utf8.GetString(bitscatalog);

// Service WSDL
byte[] bitsservice = isc.GetDescriptionDocument(servicename, servertype, "http://localhost");
string service_wsdl = utf8.GetString(bitsservice);
			

SOAP Requests and Responses

All SOAP requests to ArcGIS Server services are handled by the server object via the implementation of the IRequestHandler interface.  As a result, using the ArcObjects API a client to ArcGIS Server can use the IRequestHandler interface to submit a SOAP request and return a SOAP response.  The IRequestHandler interface defines the HandleStringRequest method to process SOAP string requests and generate SOAP string responses.  The following code example illustrates how to query interface to the IRequestHandler interface from a MapServer object, create the SOAP string request to get the default map name, and submit the request with a capability list to return a SOAP string response.  The IRequestHandler interface is included in the ESRI.ArcGIS.System.dll and referenced via the ESRI.ArcGIS.esriSystem namespace. 
 

[C#]

IRequestHandler irh = (IRequestHandler)serverContext.ServerObject;

string soap_request = "<?xml version='1.0' encoding='utf-8' ?>";
soap_request += "<soap:Envelope xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' xmlns:tns='http://www.esri.com/schemas/ArcGIS/9.2'>";
soap_request += "<soap:Body>";
soap_request += "<tns:GetDefaultMapName>";
soap_request += "</tns:GetDefaultMapName>";
soap_request += "</soap:Body>";
soap_request += "</soap:Envelope>";

string soap_response = irh.HandleStringRequest("map,query,data", soap_request);
						

Creating and parsing SOAP strings can be a labor intensive process.  Using the raw WSDL to determine how to create SOAP request and process SOAP responses can be a daunting task.  As a result, ESRI has leveraged existing technology standards coupled with developer environment utilities to make this process easier.  The following sections illustrate the technologies and utilities provided.   

Consuming SOAP Services

Developer environments, such as .NET or Java, provide SOAP toolkits to generate local, native objects as value objects and a proxy class.  The WSDL provides the client what it needs to generate the 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 services using the SOAP API

ArcGIS Server developers who want to use the SOAP API to work with ArcGIS Server services have two options to consider, depending on the connection type and client components available.

• If the Web ADF is available, use the pre-generated ArcGIS Server SOAP proxies and value objects included with the Web ADF in ESRI.ArcGIS.ADF.ArcGISServer.  For each server type that supports SOAP, two proxies are provided: a Web service proxy and a DCOM proxy.  The Web service proxy works with ArcGIS Server Web services using SOAP over HTTP and requires a url endpoint.  The DCOM proxy uses SOAP over DCOM to work with server objects via the IRequestHandler interface.  It requires an ArcGIS Server Local connection and access to server context.   In either case, the value objects utilized by the proxies are shared in the same library and same namespace.  Shared means that if multiple server types define the same value object (in the WSDL) only one value object is generated and "shared" for all proxies.  Note: the sample code provided for each server or extension type in this section illustrates the use of the Web service proxy included with the Web ADF.  
• If the Web ADF is not available, use the SOAP toolkit included with the .NET SDK to generate Web service proxies and value objects from ArcGIS Server Web service endpoints.  Without ArcObjects COM proxies on the client, no remote COM object management can occur - thus using SOAP over DCOM is not available.  Note, no ESRI products are required on the client for this option. 
  
  

In most cases, the ArcGIS Server SOAP API will be utilized when working with an ArcGIS Server Web service.   As a result, the remaining sections in this topic will focus on ArcGIS Server Web services implementation and consumption.


ArcGIS Server Web Services Implementation

In ArcGIS Server for Microsoft .NET, ArcGIS Server Web services are deployed as a compiled ASP.NET Web application which contains an HTTP Handler.   The HTTP Handler uses IServiceCatalogAdmin and IRequestHandler internally to expose the SOAP API over HTTP.  The ArcGIS Server Web service application manages all interaction with the SOAP API via ArcObjects so you don't have to.   This means ArcObjects COM proxies do not need to be on the client.  In fact, no ESRI software is required on the client to consume ArcGIS Server Web services.  Only the ability to submit and receive SOAP strings over HTTP is required.  The development environment (e.g. .NET, Java, Perl, etc.) will determine how this capability is implemented, but in the end, the ArcGIS Server Web service must receive a SOAP request and return a SOAP response.   This also means that the deployment environment of an ArcGIS Server Web service does not dictate which development environments can consume it.   An ArcGIS Server Web service can be exposed as a .NET Web service on IIS and be consumed by a Java application because the communication protocol is based on common standards (SOAP and HTTP). 


Consuming ArcGIS Server Web services

ArcGIS Server Web services use the following url pattern: 
http://<Web Server Hostname>/<ArcGIS Instance>/services/<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 "services" are made available.  Each instance is associated with one SOM.  The instance name entered during the ArcGIS Server post-install or using the AddInstance.exe utility.

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

<ServiceType> is the server object or server object extension type.  This type must provide and WSDL and implement IRequestHandler to be utilized via SOAP.

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


ArcGIS Server Proxies and Value objects

The proxy classes and value objects for each ArcGIS Server service type are generated using the service specific WSDL.  There is one proxy class for each service type.  The capabilities of an ArcGIS Server service using the SOAP API are defined by the methods of the SOAP proxy.   Recall that the SOAP API 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 capabilities of the SOAP proxy mirror the stateless ArcObjects interfaces implemented by the server object.   For example, the MapServer SOAP proxy shares the same methods as the stateless ArcObjects interfaces implemented by the ArcObjects MapServer object: IMapServer and ITiledMapServer.   The ArcGIS Server SOAP proxy uses value objects when calling a method and returning results.   As a result, SOAP value objects and ArcObjects types used by the stateless interfaces will share a common naming scheme, but are different object types.   The value objects are native .NET objects while the server object interfaces reference COM objects on the GIS Server.   For example, the MapServer SOAP proxy and IMapServer ArcObjects interface both share the method ExportMapImage.  However the SOAP proxy takes two input parameters, native .NET objects of type MapDescription and ImageDescription.  The IMapServer ArcObjects interface takes two input parameters - interface references to COM objects available on the GIS Server of type IMapDescription and IImageDescription.  The MapServer proxy returns a native .NET MapImage value object while IMapServer returns an IMapImage reference to a COM object on the GIS Server. 

The Web ADF includes SOAP proxy classes to use the SOAP API via Internet (Web service) or local (DCOM) connections.   Microsoft .NET provides a SOAP toolkit (wsdl.exe) to generate the proxy classes and value objects.   The SOAP proxies and value objects included with the Web ADF were built using the .NET SOAP toolkit - they were designed to work solely with ArcGIS Server Web services.   The DCOM proxies extend the SOAP proxies to work with local connections to ArcGIS Server and thus require connection libraries and ArcObjects COM proxies on the client.  Both SOAP and DCOM proxies share the same set of value objects.

The .NET SOAP toolkit can also be used to generate SOAP proxies and value objects dynamically, no ESRI components need to be installed or available on the client.   Thus a client application can utilize ArcGIS Server Web services using the SOAP API much like any other SOAP-based Web service. 

The table below provides the SOAP API proxy class names for the ArcGIS Server service types and their complimentary stateless interfaces in the ArcObjects API.  The SOAP API proxy classes in the Web ADF are contained in the ESRI.ArcGIS.ADF.ArcGISServer.dll assembly.  Dynamically generated Web service proxy classes share the same functionality except 1) the proxy class name will be <service name>_<server type> and 2) the namespace for the proxy and value objects is user defined.  The value object class names and properties are the same.   

The code samples below illustrate SOAP proxy class initialization with an ArcGIS Server map service:

• Web ADF - Web service proxy
  [C#]

  string endpoint = "http://MyWebServer/arcgis/services/MyMapServiceName/MapServer";
  ESRI.ArcGIS.ADF.ArcGISServer.MapServerProxy mapserver =
      new ESRI.ArcGIS.ADF.ArcGISServer.MapServerProxy(endpoint);
      

• Web ADF - DCOM proxy (also requires connection libraries ESRI.ArcGIS.ADF.dll and ESRI.ArcGIS.ADF.Connection.dll)
  [C#]

  ESRI.ArcGIS.ADF.Identity id = new ESRI.ArcGIS.ADF.Identity(username, password, domain);
  ESRI.ArcGIS.ADF.ArcGISServer.MapServerDcomProxy mapserver_dcom =
      (MapServerDcomProxy) MapServerDcomProxy.Create(SOMname, servicename, id);
  // do something with the DCOM proxy
  mapserver_dcom.Dispose();
  

• Dynamic - Web service proxy
  [C#]

  wsmap.AMapServiceName_MapServer mapserver = new wsmap.AMapServiceName_MapServer();
  mapserver.Url = http://MyWebServer/arcgis/services/MyMapServiceName/MapServer;
  

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.  To change the service for Web ADF MapServer proxy classes (which are pre-generated) the proxy constructor requires a url input parameter to define the Web service endpoint for the ArcGIS Server Web map service you want to use.    The same applies for all ArcGIS Server types: geocode services, geoprocessing services, etc.  Code samples are provided in the SOAP API discussion sections for each server type illustrating how to define which ArcGIS Server Web service will be used by a SOAP proxy. 

Walkthrough: Create an ArcGIS Server SOAP proxy and value objects dynamically using Visual Studio 2005.

In this walkthrough, we will create a desktop client application in Microsoft Visual Studio 2005 to consume an ArcGIS Server Web map service.   The MapServer proxy and value objects for the map service will be created dynamically in Visual Studio 2005 using the SOAP Toolkit (wsdl.exe) included with the .NET 2.0 SDK.  The application will use the ArcGIS Server SOAP API via the MapServer proxy and value objects to request a new map image and display it in the desktop client application.    An ArcGIS Server map service that is enabled as a Web service will be required for this walkthrough.   

Create the Windows Application project

1. In Visual Studio 2005, click File, New Project.
2. In the Add New Project dialog, under Project Types, click Visual C# Projects.
3. Under Templates, select Windows Application. For the project name, specify SOAPClient.
4. Click OK. The project will open with a form named Form1.

Add a reference to an ArcGIS Server Web map service 

1. In Solution Explorer under the SOAPClient project, right-click the References folder and select Add Web Reference.
   
   
2. In the Add Web Reference dialog, in the URL combo box, enter the Web service endpoint to the WSDL for an ArcGIS Server Web map service.  For example: http://localhost/arcgis/services/NorthAmerica/MapServer?wsdl    Note that "?wsdl" as appended to specify that the WSDL for the map service should be returned.  The methods on the MapServer SOAP proxy should be displayed.  Change the Web Reference name to something intuitive, such as "wsmap", and click Add Reference. The MapServer proxy and value objects are created for you.  Note that the Web reference name is the namespace for the MapServer proxy and value objects. 
   
   
      

Add controls the Windows form

1. Add a Button control to the form and set it's Text property to "Get Map".
2. Add a PictureBox control to the form.  Organize the controls on the form using the screenshot below.
   
   

 
Add code to get a map image and display in the PictureBox control

1. Double-click on the Get Map button to open the Form1.cs code file to the OnClick event.  The following code will use the dynamic ArcGIS Server Web service proxy and value objects to request a map image from an ArcGIS Server map service. 
2. In the OnClick event method, add the following code:
   
   Create a new instance of the MapServer proxy and set the Url property to a valid ArcGIS Server Web map service endpoint.
   
   
   [C#]

   wsmap.NorthAmerica_MapServer mapserver = new wsmap.NorthAmerica_MapServer();
   mapserver.Url = "http://localhost/arcgis/services/NorthAmerica/MapServer";
   

   
   To create a map image two value objects are required, a MapDescription and an ImageDescription.  The MapDescription provides the information on the content of the map and the ImageDescription provides image properties.   For the MapDescription, we'll use the default MapDescription of the default map data frame in the map document associated with the map service.   
   [C#]

   wsmap.MapServerInfo mapinfo = mapserver.GetServerInfo(mapserver.GetDefaultMapName());
   wsmap.MapDescription mapdesc = mapinfo.DefaultMapDescription;
   

   
   The ImageType value object stores the image format and how it will be returned to the client.  In this case, a jpeg image will be created and the url to the image on a Web server will be returned to the client.
   [C#]

   wsmap.ImageType imgtype = new wsmap.ImageType();
   imgtype.ImageFormat = wsmap.esriImageFormat.esriImageJPG;
   imgtype.ImageReturnType = wsmap.esriImageReturnType.esriImageReturnURL;
   

   
   The ImageDisplay value object stores the size and resolution of the map image.  The size is defined in pixels - in this case the size of the PictureBox control.  The image DPI is used by the map server object to calculate map scale.  It will be used to determine if scale dependent layers should be drawn and the size or width of feature or graphic symbols. 
   [C#]

   wsmap.ImageDisplay imgdisp = new wsmap.ImageDisplay();
   imgdisp.ImageHeight = pictureBox1.Height;
   imgdisp.ImageWidth = pictureBox1.Width;
   imgdisp.ImageDPI = 96;
   

   
   ImageDescription is a value object that stores a reference to the ImageDisplay and ImageType value objects.
   [C#]

   wsmap.ImageDescription imgdesc = new wsmap.ImageDescription();
   imgdesc.ImageDisplay = imgdisp;
   imgdesc.ImageType = imgtype;
   

   
   The ExportMapImage method on the MapServer proxy serializes the MapDescription and ImageDescription value objects into a SOAP request for a new map image and submits it to the Web service endpoint defined earlier.  A SOAP response is returned and the MapServer proxy deserializes the contents and returns a MapImage value object.  In this case, MapImage has a property, ImageURL, which stores the url to the map image generated by the ArcGIS Server map service. 
   [C#]

   wsmap.MapImage mapimg = mapserver.ExportMapImage(mapdesc, imgdesc);
   

   
   Using standard .NET network classes to manage HTTP requests and responses, the map image can be retrieved as a byte stream from the map image url.  A new native .NET Image is created locally in memory and assigned to the PictureBox control Image property for display. 
   [C#]

   System.Net.HttpWebRequest webreq =
       (System.Net.HttpWebRequest)System.Net.WebRequest.Create(mapimg.ImageURL);
   System.Net.HttpWebResponse webresp =
       (System.Net.HttpWebResponse)webreq.GetResponse();
   System.Drawing.Image img = System.Drawing.Image.FromStream(webresp.GetResponseStream());
   pictureBox1.Image = img;
   

Run the application
Start the application and click on the Get Map button.  The PictureBox control should display the map image generated by ArcGIS Server.