3.7 WSDL of X-Road dataservices

WSDL 1.1 documents are used for describing X-Road dataservices, to which certain restrictions apply and whose descriptions must include the obligatory elements of X-Road dataservices. Input and output parameters of dataservices are described as XML schema.

The namespace for defining dataservices is not standardised on the level of the X-Road protocol. Members/developers must discuss themselves the rules for the provision and designation of namespaces according to XML/XSD/SOAP/WSDL standards. Namespace is further discussed in module 4.

3.7.1 Description of WSDL format

WSDL describes dataservices in XML format, along with input and output messages of these dataservices, and with which protocols and address dataservices are retrieved.

Figure 14 Structure of WSDL 1.1

Figure 14 presents the structure of WSDL description with a structure in XML format below. After the general structure, we will look separately at the specific blocks – types, message, portType, binding and service.

<wsdl:definitions name=”person_register” targetNamespace=”http://persons_register.x-road.ee”>

<wsdl:import namespace=”http://x-road.eu/xsd/xroad.xsd” location=”http://x-road.eu/xsd/xroad.xsd"/>

  <wsdl:types>

    <xsd:schema> … </xsd:schema>

  </wsdl:types>

  <wsdl:message> … </wsdl:message>

  <wsdl:portType>

    <wsdl:operation>

      <wsdl:input> … </wsdl:input>

      <wsdl:output> … </wsdl:output>

    </wsdl:operation>

  </wsdl:portType>

  <wsdl:binding> … </wsdl:binding>

  <wsdl:service>

    <wsdl:port> … </wsdl:port>

  </wsdl:service>

</wsdl:definitions>

3.7.2 types

In the block <types> of WSDL description, definitions of data types and elements are described as XML schema. Schemas may be located inside a WSDL document, but can also be imported from outside. Import of schemas is further discussed in clause 3.9.

Example of an XML schema:

<xsd:schema targetNamespace="http://persons_register.x-road.ee">

  <xsd:element name="personList">

    <xsd:complexType>

      <xsd:sequence>

        <xsd:element name="firstName" type="xsd:string">

          <xsd:annotation>

            <xsd:appinfo>

              <xrd:title xml:lang="et">Eesnimi</xrd:title>

            </xsd:appinfo>

          </xsd:annotation>

        </xsd:element>

        <xsd:element name="lastName" type="xsd:string">

          <xsd:annotation>

            <xsd:appinfo>

              <xrd:title xml:lang="et">Perenimi</xrd:title>

            </xsd:appinfo>

          </xsd:annotation>

        </xsd:element>

      </xsd:sequence>

    </xsd:complexType>

  </xsd:element>

  <xsd:element name="personListResponse">

    <xsd:complexType>

      <xsd:sequence>

        <xsd:element name="person" type="tns:person" />

      </xsd:sequence>

    </xsd:complexType>

  </xsd:element>

  <xsd:complexType name="contact">

    <xsd:sequence>

      <xsd:element name="phone" type="xsd:string" maxOccurs="unbounded" minOccurs="0" />

      <xsd:element name="e-mail" type="xsd:string" maxOccurs="unbounded" minOccurs="0" />

      <xsd:element name="address" type="xsd:string" maxOccurs="1" minOccurs="0" />

    </xsd:sequence>

  </xsd:complexType>

  <xsd:complexType name="person">

    <xsd:sequence>

      <xsd:element name="personId" type="xsd:string" />

      <xsd:element name="firstName" type="xsd:string" />

      <xsd:element name="lastName" type="xsd:string" />

      <xsd:element name="birthDate" type="xsd:date" />

      <xsd:element name="personContact" type="tns:contact" />

    </xsd:sequence>

  </xsd:complexType>

</xsd:schema>

Complex-type element personList includes two sub-elements firstName and lastName, annotated with xrd:title documentation element. To ensure clearer explanation of the structure, we have not described here the xrd:title documentation element for other elements. The sub-element of the complex-type element personListResponse is person, the type of which is the complex element person defined in the same schema, with sub-elements personId, firstName, lastName, birthDate, personContact. The type of the latter – personContact – is the contact described in the same schema, with sub-elements phone, e-mail, and address.

3.7.3 message

<message> blocks of WSDL description describe message types formed of the elements of XML schema described in <types> block. On X-Road, message is also defined for describing header fields.

<wsdl:message name="xrdheader">

                <wsdl:part name="client" element="xrd:client"/>

                <wsdl:part name="service" element="xrd:service"/>

                <wsdl:part name="userId" element="xrd:userId"/>

                <wsdl:part name="id" element="xrd:id"/>

                <wsdl:part name="protocolVersion" element="xrd:protocolVersion"/>

</wsdl:message>

<wsdl:message name="personListRequest">

                <wsdl:part element="tns:personList" name="parameters"/>

</wsdl:message>

<wsdl:message name="personListResponse">

                <wsdl:part element="tns:personListResponse" name="parameters"/>

</wsdl:message>

3.7.4 portType

<portType > block of WSDL description describes names of X-Road dataservices <operation> and binds input and output of dataservice to the message types described in <message> blocks. personList is the name of dataservice and personListRequest and personListResponse are input and output messages corresponding to the dataservice.

<wsdl:portType name="person_register">

                <wsdl:operation name="personList">

                               <wsdl:documentation>

                                               <xrd:title xml:lang="et">Isikute nimekirja küsimine nime järgi</xrd:title>

                               </wsdl:documentation>

                               <wsdl:input message="tns:personListRequest"/>

                               <wsdl:output message="tns:personListResponse"/>

                </wsdl:operation>

</wsdl:portType>

3.7.5 binding (binding of dataservice and message protocol)

The <binding> part of WSDL document describes how to bind dataservice with the message protocol. On X-Road, the style Document/literal wrapped is used for binding dataservice and the message protocol. For specifying the Document/literal wrapped style, it is necessary to specify in the <binding> part of the WSDL document the style style=”document” and literal use use=”literal”, as shown in the following fragment of WSDL document. Transport protocol (HTTP) and header fields of SOAP message are also specified in the <binding> part.

<wsdl:binding name="person_registerSOAP" type="tns:person_register">

  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>

  <wsdl:operation name="personList">

    <soap:operation soapAction=""/>

      <xrd:version>v1</xrd:version>

        <wsdl:input name=”personList”>

          <soap:body use="literal"/>

          <soap:header message="tns:xrdheader" part="client" use="literal"/>

          <soap:header message="tns:xrdheader" part="service" use="literal"/>

          <soap:header message="tns:xrdheader" part="userId" use="literal"/>

          <soap:header message="tns:xrdheader" part="id" use="literal"/>

          <soap:header message="tns:xrdheader" part="protocolVersion" use="literal"/>

        </wsdl:input>

        <wsdl:output name=”personListResponse”>

          <soap:body use="literal"/>

          <soap:header message="tns:xrdheader" part="client" use="literal"/>

          <soap:header message="tns:xrdheader" part="service" use="literal"/>

          <soap:header message="tns:xrdheader" part="userId" use="literal"/>

          <soap:header message="tns:xrdheader" part="id" use="literal"/>

          <soap:header message="tns:xrdheader" part="protocolVersion" use="literal"/>

        </wsdl:output>

    </wsdl:operation>

</wsdl:binding>


Unlike RPC style, in the case of Document style, SOAP body does not include the name of WSDL operation, but only the content of the request. The literal use of Document style means that elements types can be derived from the XML schema and the encoding information of types is not repeated in the body of SOAP protocol.

In the case of Document/literal wrapped style, wrappers are generated for message parameters in XML schema, whereby the wrapper of input parameters of the message has the same name as WSDL operation, and the wrapper of output parameters is obtained by adding ‘Response’ to the operation name. Due to the specificity of X-Road, the value of the serviceCode field of SOAP header must match the name of the wrapper of input parameters of the message. An advantage of the wrapped style compared to a non-wrapped style is that the name of the operation to be retrieved can be read from the body of SOAP protocol.

Since x-road version 6.18.0 securityserver checks and forwards SOAPAction field in HTTP headers. In previous versions of x-road securityserver removed SOAPAction from HTTP headers before fowarding it. So now it is important that the heared is defined correctly according to standard section 6.1.1. SOAPAction value can be empty or string surrounded by quotes. In any other case Securityserver will return error message The given SOAPAction ... does not match an operation ja Malformed SOAPAction header. 

For example, if you come across services with the style rpc/encoded in the descriptions of X-Road dataservices, this is a dataservice of an older X-Road version, and the description must be transferred into the style document/literal wrapped for Version 6.

See more at: https://www.ibm.com/developerworks/library/ws-whichwsdl/

3.7.6 service

In the <service> block of WSDL description, a specific URL of dataservice is defined.

<wsdl:service name="person_register">

  <wsdl:port binding="tns:person_registerSOAP" name="person_registerSOAP">

    <soap:address location="http://localhost:8080/person_register/services/person_registerSOAP"/>

  </wsdl:port>

</wsdl:service>




Viimati muudetud: esmaspäev, 5. november 2018, 14.38