SOAP Web Service con PHP: l'interfaccia WDSL

Nella lezione precedente abbiamo introdotto il protocollo SOAP ed il file WSDL utilizzato come interfaccia per lo scambio di informazioni. Possiamo a questo punto realizzare un esempio di client/server che utilizzano il protocollo SOAP.

Nel nostro esempio creeremo un server di un archivio libri che, data una richiesta basato sull'id di un libro, restituisce l'oggetto con tutte le sue informazioni.

L'interfaccia WDSL

Il file WSDL è rappresentato da un file XML che chiameremo books.wsdl. In esso definiremo un tipo di dato complesso che chiameremo book e che rappresenterà l'oggetto Book restituito dal server.

<wsdl:types>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="Library">
        <xsd:complexType name="book">
            <xsd:sequence>
                <xsd:element name="name" type="xsd:string"></xsd:element>
                <xsd:element name="year" type="tns:integer"></xsd:element>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:schema>
</wsdl:types>

Nell'esempio l'oggetto book ha al suo interno due proprietà:

1. una stringa name.
2. un intero year.

Andremo poi a definire i message, ovvero i tipi di dato che è possibile scambiare tra client e server. Nel nostro caso un intero per la richiesta contenente l'id del libro e un tipo book utilizzato per la risposta:

<wsdl:message name="bookRequest">
    <wsdl:part name="id" type="tns:integer"></wsdl:part>
</wsdl:message>
<wsdl:message name="bookResponse">
    <wsdl:part name="book" type="xsd:book"></wsdl:part>
</wsdl:message>

A questo punto andiamo a combinare i due messaggi per definire il portType, cioè una delle operazioni possibili con il Web Service. La nostra operazione si chiama getBook ed è quella che il client richiamerà per recuperare le informazioni di un libro:

<wsdl:portType name="Library">
    <wsdl:operation name="getBook">
        <wsdl:input message="tns:bookRequest"/>
        <wsdl:output message="tns:bookResponse"/>
    </wsdl:operation>
</wsdl:portType>

Infine utilizziamo il binding per stabilire come l'operazione definita precedentemente viene trasmessa tra client e server e dove è possibile trovarla nel server:

<wsdl:binding name="Library" type="tns:Library">
    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="getBook">
        <soap:operation soapAction="http://example.com/server.php"/>
        <wsdl:input>
            <soap:body use="literal" namespace="Library"/>
        </wsdl:input>
        <wsdl:output>
            <soap:body use="literal" namespace="Library"/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

Combinando il tutto avremo un risultato simile al seguente:

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="Library"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  targetNamespace="Library"
                  xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
                  xmlns:tns="Library"
                  xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <xsd:documentation></xsd:documentation>
    <wsdl:types>
        <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="Library">
            <xsd:complexType name="book">
                <xsd:sequence>
                    <xsd:element name="name" type="xsd:string"></xsd:element>
                    <xsd:element name="year" type="tns:integer"></xsd:element>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:schema>
    </wsdl:types>
    <wsdl:message name="bookRequest">
        <wsdl:part name="id" type="tns:integer"></wsdl:part>
    </wsdl:message>
    <wsdl:message name="bookResponse">
        <wsdl:part name="book" type="xsd:book"></wsdl:part>
    </wsdl:message>
    <wsdl:portType name="Library">
        <wsdl:operation name="getBook">
            <wsdl:input message="tns:bookRequest"/>
            <wsdl:output message="tns:bookResponse"/>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="Library" type="tns:Library">
        <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="getBook">
            <soap:operation soapAction="http://example.com/server.php"/>
            <wsdl:input>
                <soap:body use="literal" namespace="Library"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" namespace="Library"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="Library">
        <wsdl:port binding="tns:Library" name="BookLibrary">
            <soap:address location="http://example.com/server.php"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

Prestiamo attenzione alla url http://example.com che dovremo sostituire con quella effettiva. Nel prossimo capitolo analizzeremo la parte relativa all'implementazione del server.