Consuming a XML over REST API

[gigerIT]

Hello Everyone

I noticed that there are a lot of skilled and experienced developers active on this repo, so we decided to ask if someone knows any better approach then the "hacky" way we came up with.

We need to consume a XML over REST API from our PHP project, so we came across this package (as it is the only one who generates everything we need from the APIs wsdl).

As the API does not use soap we decided to create a request and response manipulator who does strip all "soapish" elements the API doesn't accept.

That middleware currently looks like this:

class SoapToRestXmlMiddleware implements Plugin
{
    public function handleRequest(RequestInterface $request, callable $next, callable $first): Promise
    {
        $request = (new XmlMessageManipulator)(
            $request,
            function (Document $document) {
                $bodyElement = $document->locate(new SoapBodyLocator());

                $requestElement = $bodyElement->firstElementChild->firstElementChild;
                $requestElement->setAttribute('xmlns', 'http://schemas.apiendpoint.com/1.2.1');
                $requestElement->removeAttribute('xsi:type');

                foreach ($requestElement->getElementsByTagName('*') as $element) {
                    $element->removeAttribute('xsi:type');
                }

               $document->manipulate(function (\DOMDocument $domDocument) use ($requestElement) {

                    //clear the whole dom document
                    foreach ($domDocument->getElementsByTagName('*') as $element) {
                        $domDocument->removeChild($element);
                    }

                    //attach the new cleaned request element
                    $domDocument->append($requestElement);
                });


                return $document;
            }
        );
        return $next($request);
    }
}

Which turns:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://schemas.apiendpoint.org/1.2.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
    <SOAP-ENV:Body>
        <ns1:GetRoutes>
            <GetRoutesRequest xsi:type="ns1:GetRoutesRequestType" OperatorCode="TEST123">
                <Context AgentAccountNumber="ABCD123456" CountryCode="CHE" Currency="EUR" LanguagePrefCode="en" TransactionId="75961016" ExternalBookingReference="Test001" User="Test001" xsi:type="ns1:ContextType"/>
            </GetRoutesRequest>
        </ns1:GetRoutes>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Into:

<?xml version="1.0" encoding="utf-8"?>
<GetRoutesRequest OperatorCode="TEST123" xmlns="http://schemas.apiendpoint.org/1.2.1">
    <Context AgentAccountNumber="ABCD123456" TimeStamp="2018-02-08T21:00:00" CountryCode="CHE" Currency="EUR" LanguagePrefCode="en" TransactionId="75961016" ExternalBookingReference="Test001" User="Test001" />
</GetRoutesRequest>

We would now have to add a manipulator for the response as well to re add the soap elements (envelope etc.) so the decoder can parse it.

We only started to work with this soap client last week, so if anyone with more experience has an idea how to do that in a better way, we would really appreciate your input.

[veewee]

Hello,

Having a WSDL without a SOAP accepting endpoint: Can you tell me how this works?
Is it possible to share the service definition?

This tool is not really designed to be able to do that.
Maybe once we add a vanilla PHP engine, it could be possible to encode / decode part of a soap message.
Sadly, we are not close to that point yet, especially due to time constraints.

I did make a custom decoder a couple of months ago in a private repo, which is decoding XML into mock objects
For example:

    private function labels()
    {
        return $this->decodeObject(
            <<<EOXML
                <Labels>
                    <Label Code="PRODUCTCODE">
                     XXXX
                    </Label>
                </Labels>
               EOXML
        );
    }

This results in a prohpecy mock object Labels - which contains another Label mock object.
The logic for that was quite straight forward: use the name of the tag and use the normalizer in this package to detect the classname. Next fill it up with the attributes and/or content.

I think that would be a better approach than trying to remove / reconstruct parts of the xml.

Another thing you might be able to do, is using the veewee/xml encoding/decoding feature:
https://github.com/veewee/xml/blob/master/docs/encoding.md

You could be able to:

• encode: serialize objects to an array format with eg JWT serializer, transform array into xml
• decode: decode xml into array, hydrate object from array with a serializer.

In any case: I'm quite interested in the solutiion you come up with. So feel free to share how you did it.
We need a package like this at some point in time, but for now the next big job from our side is fetching metadata from the wsdl and using that to improve the generated types.

[gigerIT]

Hi

Yes I was confused as well, I've worked with SOAP APIs before but never heard of such an approach.
They provide a wsdl, xsd etc. but don't accept SOAP requests (I'll check if im allowed to share the files).

Thanks for your input, we will definitely use that decoding/encoding package (manipulating DOMElements is a real pain).
I'll share our final middleware once it is fully working.

In the meantime another question came up regarding the package which you might know by heart but is giving us a hard time.
The response is returned to the client wrapped in a "phpro\SoapClient\Type\MixedResult" which has the actual response class as property inside.

This of course throws an error for the returned type:
Fatal error: Uncaught TypeError: OurappClient::getRoutes(): Return value must be of type Ourapp\Api\Types\GetRoutesResponseType, Phpro\SoapClient\Type\MixedResult returned

Do you have any idea why the SOAP decoder wraps the response in that MixedResult?

Response returned to the client:

Raw response decoder receives:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://schemas.apiendpoint.org/1.2.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <SOAP-ENV:Body>
      <ns1:GetRoutes>
         <GetRoutesResponse xmlns="http://schemas.apiendpoint.org/1.2.1" xsi:type="ns1:GetRoutesResponseType">
            <Context xsi:type="ns1:ContextType" AgentAccountNumber="TESTAGENT01" CountryCode="CHE" Currency="EUR" LanguagePrefCode="en" TimeStamp="2022-05-16T12:25:16" ExternalBookingReference="Test001" User="Test001" TransactionId="77820857" />
            <Routes xsi:type="ns1:RoutesType">
               <Route DepartPort="TEST01" DepartPortCountry="FIN" DepartPortName="TEST01name" DestinationPort="TEST01" DestinationPortCountry="FIN" DestinationPortName="TEST01name" OperatorCode="TESTOPERATOR01" />
               <Route DepartPort="TEST01" DepartPortCountry="FIN" DepartPortName="TEST01name" DestinationPort="TEST02" DestinationPortCountry="EST" DestinationPortName="Test02Name" OperatorCode="TESTOPERATOR01" />
            </Routes>
         </GetRoutesResponse>
      </ns1:GetRoutes>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

[veewee]

No idea why it wraps the result in a SoapVar to be honest.
Is this a response you constructed manually then? I might assume that the <ns1:GetRoutes> should be removed.
Instead it returns the GetRoutesResponse directly?

[gigerIT]

Yes this is the response we assembled ourselves back to the SOAP style.
Without the <ns1:GetRoutes> it gets even weirder, it then ignores completely the GetRoutesResponseType and puts the two child elements into an array inside MixedResult.

I guess it must be something wrong with our response.
Are there any examples what the decoder typically expects as response?

I could just do:

return ($this->caller)('GetRoutes', $GetRoutesRequest)->getResult()->enc_value;

and it would work, but it's not pretty.

[veewee]

Maybe a namespace mismatch? I don't have a clue to be honest.
You might be better of using a custom serializer for this purpose instead of trying to do SOAP whilst there is just regular XML available.