Publication Date: 2017-06-16

Approval Date: 2017-02-20

Posted Date: 2016-11-03

Reference number of this document: OGC 16-138

Reference URL for this document: http://www.opengis.net/doc/PER/t12-A061

Category: User Guide

Editor: Peter Baumann

Title: Testbed-12 OWS SOAP User Guide


COPYRIGHT

Copyright © 2017 Open Geospatial Consortium. To obtain additional rights of use, visit http://www.opengeospatial.org/

Important

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights. Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

Note

This document is a user guide created as a deliverable in an OGC Interoperability Initiative as a user guide to the work of that initiative and is not an official position of the OGC membership. There may be additional valid approaches beyond what is described in this user guide.


POINTS OF CONTACT

Name

Organization

Peter Baumann

Jacobs University

Andreas Matheus

Secure Dimensions

Ziheng Sun

GMU

Sheng Wu

ASU

Jeff Harrison

CarbonCloud


1. Introduction

This OGC Engineering Report provides guidance for using SOAP in the context of OGC Web Services (OWSs). Use is exemplified on three core services, Web Map Service (WMS), Web Feature Service (WFS), and Web Coverage Service (WCS).

We start with a brief overview on SOAP. Another primer is available, e.g., from w3schools.com. A study on the practical use of SOAP has been conducted in [EC-SOAP].

1.1. SOAP Primer

The user guide addresses three parts: The interface or API part, the service part, and the client part. All parts can be looked at separately, but are not isolated from each other. They are all linked (related) to each other by a common description of the service interface using a Web Services Description Language (WSDL). Commonly, a WSDL file defines the SOAP message structure (data types, messages, operations and service endpoints including a binding for the operations) that is mandated by the service and to be sent by the client.

fig1
Figure 1. Relationship between a SOAP enabled (OGC) Web Service, its API, and a client application

It seems to be reasonable to assume that a service side development produces at some stage the API. This can either happen by creating an interoperable description of the API, e.g. using IDL or WSDL. However, the description of an API can also be done via an OGC interface standard. (Note that "API", aka Application Programming Interface, is understood in a very general sense including, beyond direct function invocation, also Web service request protocols etc.) Therefore, the use of e.g. a WSDL must be considered optional but would improve the interoperability via automatic code generation but preventing misinterpretation of the English language. In any case where the API involves security, it is reasonable to request a machine-readable version of the API, aka a WSDL file.

We start with the interface (API), proceed with the service side development and implementation, and finally address client implementation.

1.2. SOAP API

It seems to be reasonable to assume that a service side development produces at some stage the API. This can either happen by creating an interoperable description of the API, e.g. using IDL or WSDL. However, the description of an API can also be done via an OGC implementation standard. Therefore, the use of e.g. a WSDL must be considered optional but would improve the interoperability via automatic code generation but preventing misinterpretation of the English language. In any case where the API involves security, it is reasonable to request a machine-readable version of the API, aka a WSDL file.

fig2
Figure 2. UML-alike presentation of building blocks for a SOAP-based Web Service

As illustrated in the figure above, it is important to understand the overall relationships between all the building blocks that exist in the OGC Web Services world to develop a service and the client involving security. The most important aspect that can be isolated from the figure above is that it reflects the two basic approaches for developing the client application:

  1. The client application development is directly using the service API implementation as defined in the service WSDL. The developer can use a tool to auto-generate the relevant code. For example, a WSDL2Java transformer could have been used. With this approach, the client application does use the service interface as defined in the WSDL.

  2. The client application development is based on some other description of the service API / interface. For example, the client application developer can use the appropriate OGC Web Service specification(s) to implement the code that uses the service interface properly.

Regardless of the approach, it is important to note that the service instance implements the API defined by the WSDL. This does guarantee immediate interoperability for the client type #1 because the auto-generated client stubs fit exactly the service implementation. This is in particular important in cases where a WS-SecurityPolicy is used that declare the security requirements for the SOAP envelope.

It is therefore recommended that for each SOAP enabled OGC Web Service instance, a WSDL is provided that is capable to support the auto-generation of client stubs. At this point it is important to note that the use of a WSDL document is not sufficient by itself; a Capabilities document is still required, as we will illustrate in a later section.

1.3. WSDL

The Web Services Description Language (WSDL) is a W3C standard that allows creating a machine-readable description of a web service instance. In a nutshell, the WSDL separates this description is multiple sections:

  1. The Data Type section supports the definition of simple and complex data structures for the target encoding XML.

  2. The Message section supports the definition of XML encoded messages that are inbound and outbound to the service.

  3. The Operation section relates messages to Operations.

  4. The Binding section associates the operations to a particular binding, e.g. SOAP.

  5. The Service section finally completes the service instance description with providing a network endpoint for the binding(s).

A WSDL instance document excluding the Service section can be seen as a service type specific description of SOAP enabled OGC Web Service. Such a WSDL document can therefore be used to auto-generate a library that includes the capabilities to marshal and unmarshal service type specific message structures, encoded in XML. In order to achieve the auto-generation, it is required that – at the end – all message structures are well defined. This requires in particular, that all data types be based on valid XML Schema.

1.4. Implementation Aspects

It is important to understand that the implementation of a client application for SOAP enabled OGC Web Services requires the Capabilities document and optionally the service. As illustrated above, the implementation of a client application for SOAP enabled OGC Web Services can be described as a step-by-step approach:

  1. Creating the SOAP message library from the WSDL -> SOAP Library

  2. Implementing a service type specific API that instruments the SOAP message creation based on parsing the Capabilities -> Operation Library

  3. Developing the GUI part of the application to reflect user specific requirements

For the creation of the SOAP Library and its programming language specific implementation, different tools exit. For example the Apache CXF WSDL2Java tool is capable to create a complete SOAP message API and all required calls to the network libraries to communicate with the service. In case that a developer intends to create a generic SOAP API, the tools must omit the <Service> definition section of the WSDL. The resulting code is capable to marshal and unmarshal SOAP messages specific for the definitions in the WSDL.

The following Figure 3 illustrates the different layers for a SOAP supporting client including the SOAP library (layer 6) and the Capabilities library (layer 7). With these libraries in place, the client application always communicates with the Capabilities Library, which is a specialization of the generic SOAP library. The overarching basis is the network communication library, which is used by the SOAP library in the case the SOAP library is auto-generated from a service instance WSDL document.

fig3
Figure 3. Software stack for Client Applications supporting SOAP and Security

1.5. References

[EC-SOAP] Matteo Villa, Roberto Lucchi, Michel Millot, Ioannis Kanellopoulos (eds.): SOAP HTTP Binding Status - Survey on OGC and ORCHESTRA specifications relevant for the INSPIRE Network Services. JRC Scientific and Technical Reports, 2008; http://inspire.ec.europa.eu/reports/ImplementingRules/network/SOAP_binding_survey.pdf

2. OGC Web Services over SOAP

In this section, core OGC Web service standards - WCS, WFS, and WMS - are being inspected with respect to their SOAP support.

2.1. Web Coverage Service (WCS) over SOAP

Starting WCS 2, SOAP is supported as a so-called protocol binding [OGC 09-149r1]. The philosophy behind is that protocol binding and encoding is separated from functionality (such as service extensions like range subsetting or CRS transformation) to achieve orthogonality. This allows maximizing use of WCS in diverse environments and setups without compromising interoperability.

In the sequel, we describe how to use SOAP in WCS 2 (note that WCS 1.x is a deprecated old version, incompatible to WCS 2 as per OGC’s version management directives).

2.1.1. WCS-SOAP Definitions

The OGC Web Coverage Service (WCS) supports electronic retrieval of geospatial data as "coverages" – that is, digital geospatial information representing space/time-varying phenomena. The WCS SOAP Extension standard specifies a SOAP protocol binding to the OGC Web Coverage Service (WCS) 2.0 core to allow for client/server communication using SOAP with XML encoding.

Seven requirements describe the use of SOAP for WCS communication:

  • Requirement 1: A WCS service implementing this extension shall include the following URI in the Pro-file element of the ServiceIdentification in a GetCapabilities response: http://www.opengis.net/spec/WCS_protocol-binding_soap/1.0

  • Requirement 2: For those WCSServiceMetadata elements inherited from OWSServiceMetadata, WCS servers shall specify the HTTP POST request encodings accepted by including an ows:Constraint element, with “PostEncoding” as the value of the name attribute and with a value of “SOAP” to indicate that SOAP encoding is allowed.

  • Requirement 3: WCS servers and clients implementing this protocol shall adhere to SOAP 1.2 for all WCS operation requests and responses. The SOAP Request-Response message exchange pattern shall be used with the HTTP POST binding.

  • Requirement 4: Each XML-encoded operation request and response shall consist of one SOAP Envelope containing exactly one Body. In a request, each Body shall contain exactly one WCS request.

  • Requirement 5: A GetCoverage SOAP response shall be encoded as “SOAP with Attachments” as defined in [W3C Note 11], but using SOAP 1.2 rather than SOAP 1.1.

  • Requirement 6: In a GetCoverage response, the SOAP Envelope shall contain one Body element which contains the Coverage as its single element.

  • Requirement 7: When an error is detected while processing an operation request encoded in a SOAP envelope, the WCS server shall generate a SOAP response message where the content of the Body element is a Fault element containing an ows:ExceptionReport element [OGC 06-121r9], with the soap:Value element element having the fixed string “soap:server” and the soap:Text having the fixed string “Server exception was encountered.” (Note : This fixed string is used since the details of the exception shall be specified in the Detail element using an ows:ExceptionReport element as specified in OWS Common [OGC 06-121r9].) Further, there is a requirement describing WCS SOAP bindings, see file wcs-soap-binding.wsdl provided in the wsdl/ subdirectory of the WCS XML schema tree. There is just one requirement on WSDL:

  • Requirement 8: Publication of a WCS SOAP service endpoint shall use the binding as defined in file wsdl/wcs-soap-binding.wsdl of the WCS XML package.

This definition looks as follows:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="http://www.opengis.net/wcs/2.0"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:wcs="http://www.opengis.net/wcs/2.0"
    xmlns:ows="http://www.opengis.net/ows/2.0"
    xmlns:gml="http://www.opengis.net/gml/3.2"
    xmlns:gmlcov="http://www.opengis.net/gmlcov/1.0"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <wsdl:documentation xmlns:dc="http://purl.org/dc/elements/1.1/">
        <dc:identifier>http://www.opengis.net/def/objectType/OGC-WCS/0/WSDL-Interface</dc:identifier>
        <dc:date>2010-apr-14</dc:date>
        <dc:description>
            This is the normative service interface definition for the SOAP protocol
            binding of the OGC Web Coverage Service v2.0.
            WSDL 1.1 syntax is used to describe interface signatures and message structures.

            The intention is that individual implementations will establish something like
            *-endpoint(s).wsdl files, and will provide (possibly restricted) versions of
            *-binding(s).wsdl files, depending on the interfaces that the implementation on
            hand supports.

            Copyright (c) 2010 Open Geospatial Consortium, Inc. All Rights Reserved.
            To obtain additional rights of use, visit http://www.opengeospatial.org/legal/.
        </dc:description>
    </wsdl:documentation>

    <!-- ============================================================== -->
    <!-- WCS request/response types                                     -->
    <!-- ============================================================== -->
    <wsdl:types>
        <xsd:schema targetNamespace="http://www.opengis.net/wcs/2.0"
            xmlns:wcs="http://www.opengis.net/wcs/2.0"
            elementFormDefault="qualified" version="2.0.1">
            <xsd:include schemaLocation="http://schemas.opengis.net/wcs/2.0/wcsAll.xsd"/>
        </xsd:schema>
    </wsdl:types>

    <!-- ============================================================== -->
    <!-- WCS request messages                                           -->
    <!-- ============================================================== -->
    <wsdl:message name="GetCapabilitiesRequest">
        <wsdl:part name="Body" element="wcs:GetCapabilities"/>
    </wsdl:message>
    <wsdl:message name="DescribeCoverageRequest">
        <wsdl:part name="Body" element="wcs:DescribeCoverage"/>
    </wsdl:message>
    <wsdl:message name="GetCoverageRequest">
        <wsdl:part name="Body" element="wcs:GetCoverage"/>
    </wsdl:message>

    <!-- ============================================================== -->
    <!-- WCS response messages                                          -->
    <!-- ============================================================== -->
    <wsdl:message name="GetCapabilitiesResponse">
        <wsdl:part name="Body" element="wcs:Capabilities"/>
    </wsdl:message>
    <wsdl:message name="DescribeCoverageResponse">
        <wsdl:part name="Body" element="wcs:CoverageDescriptions"/>
    </wsdl:message>
    <wsdl:message name="GetCoverageResponse">
        <wsdl:part name="Body" element="gmlcov:AbstractCoverage"/>
    </wsdl:message>
    <wsdl:message name="ServiceExceptionReport">
        <wsdl:part name="Body" element="ows:ExceptionReport"/>
    </wsdl:message>

    <!-- ============================================================== -->
    <!-- WCS port                                                       -->
    <!-- ============================================================== -->
    <wsdl:portType name="WcsPortType">
        <wsdl:operation name="GetCapabilitiesOperation">
            <wsdl:input message="GetCapabilitiesRequest"/>
            <wsdl:output message="GetCapabilitiesResponse"/>
            <wsdl:fault name="ServiceExceptionReport" message="ServiceExceptionReport"/>
        </wsdl:operation>
        <wsdl:operation name="DescribeCoverageOperation">
            <wsdl:input message="DescribeCoverageTypeRequest"/>
            <wsdl:output message="DescribeCoverageTypeResponse"/>
            <wsdl:fault name="ServiceExceptionReport" message="ServiceExceptionReport"/>
        </wsdl:operation>
        <wsdl:operation name="GetCoverageOperation">
            <wsdl:input message="GetCoverageRequest"/>
            <wsdl:output message="GetCoverageResponse"/>
            <wsdl:fault name="ServiceExceptionReport" message="ServiceExceptionReport"/>
        </wsdl:operation>
    </wsdl:portType>

    <!-- ============================================================== -->
    <!-- WCS binding                                                    -->
    <!-- ============================================================== -->
    <wsdl:binding name="WcsSoapBinding" type="WcsPortType">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="GetCapabilitiesOperation">
            <soap:operation/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
            <wsdl:fault name="ServiceExceptionReport">
                <soap:fault name="ServiceExceptionReport" use="literal"/>
            </wsdl:fault>
        </wsdl:operation>
        <wsdl:operation name="DescribeCoverageOperation">
            <soap:operation/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
            <wsdl:fault name="ServiceExceptionReport">
                <soap:fault name="ServiceExceptionReport" use="literal"/>
            </wsdl:fault>
        </wsdl:operation>
        <wsdl:operation name="GetCoverageOperation">
            <soap:operation/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
            <wsdl:fault name="ServiceExceptionReport">
                <soap:fault name="ServiceExceptionReport" use="literal"/>
            </wsdl:fault>
        </wsdl:operation>
    </wsdl:binding>

    <!-- ============================================================== -->
    <!-- WCS service                                                    -->
    <!-- ============================================================== -->
    <!-- this section describes the concrete service instance, hence    -->
    <!-- cannot be provided in advance. See example-soap-endpoint.wsdl  -->
    <!-- for an example of setting up a concrete service description.   -->

</wsdl:definitions>

A sample service description relying on this binding is provided in file example-soap-endpoint.wsdl, which is copied below and can be reused (with URLs, service name, etc. adapted):

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions
    targetNamespace="http://www.myservice.com/wcs"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
    <wsdl:documentation xmlns:dc="http://purl.org/dc/elements/1.1/">
        <dc:date>2010-apr-14</dc:date>
        <dc:description>
            This WSDL document specifies, by way of an example, the service-specific
            properties of a WCS service based on the generic definitions provided
            with the WCS WSDL specification imported below.

            Copyright (c) 2010 Open Geospatial Consortium, Inc. All Rights Reserved.
            To obtain additional rights of use, visit http://www.opengeospatial.org/legal/.
        </dc:description>
    </wsdl:documentation>

    <wsdl:import namespace="http://www.opengis.net/wcs/wsdl" location="./wcs-soap-binding.wsdl"/>

    <!-- ============================================================== -->
    <!-- sample WCS service, relying on the standard SOAP binding       -->
    <!-- ============================================================== -->
    <!-- adapt this below to your particular service:                   -->

    <wsdl:service name="MyFabulousWCS">
        <wsdl:documentation>
            A WCS 2.0 service instance which implements the WCS SOAP protocol binding extension.
        </wsdl:documentation>
        <wsdl:port name="WcsSoapPort" binding="WcsSoapBinding">
            <soap:address location="http://www.myservice.com/wcs-soap"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

To allow WCS extensions to add further parameters the XML Schema wcs:Request-BaseType contains an optional element <extension> with unbounded cardinality. This way, extensions can add their individual request parameters without (syntactic) interference.

2.1.2. WCS-SOAP in Practice

WCS services offering SOAP support have been stood up in Testbed 12 by Jacobs University and George Mason University. In the sequel, we describe both.

Jacobs University WCS-SOAP
  • WCS GetCoverage request:

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
    <env:Header/>
    <env:Body>
        <wcs:GetCoverage xmlns:wcs="http://www.opengis.net/wcs/2.0"
            xmlns:gml="http://www.opengis.net/gml/3.2"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://www.opengis.net/wcs/2.0 ../../wcsAll.xsd"
            service="WCS" version="2.0.0">
            <wcs:CoverageId>BlueMarbleCov</wcs:CoverageId>
            <wcs:DimensionTrim>
                <wcs:Dimension>Lat</wcs:Dimension>
                <wcs:TrimLow>10</wcs:TrimLow>
                <wcs:TrimHigh>20</wcs:TrimHigh>
            </wcs:DimensionTrim>
            <wcs:DimensionTrim>
                <wcs:Dimension>Long</wcs:Dimension>
                <wcs:TrimLow>10</wcs:TrimLow>
                <wcs:TrimHigh>30</wcs:TrimHigh>
            </wcs:DimensionTrim>
       <gml:format>image/tiff</gml:format>
        </wcs:GetCoverage>
    </env:Body>
</env:Envelope>
  • Response: