Search code examples
javaphp.netmagentomagento-soap-api

What do the V2 and WSI Magento SOAP Interfaces do?

Magento has a "Webservices API" that's accesible via SOAP and RPC.

The terminology gets a screwy here, as the SOAP (or RPC) API itself only exposes 8 methods. To access a method in the Magento API you call the SOAP api method call, and then pass in a string that indicates the method you really want to call, (something like catalog_product.info)

Over the years the Magento team introduced two additional API backends, SOAP V2, and SOAP WSI. These backends were introduced "To increase compatibility with .NET and Java"

What does this mean, exactly? From a code point of view these APIs change the WSDL that's exposed, and when using PHP's SOAP client the whole call thing goes away. You're calling actual methods on the client itself goes away

$client->call($session, 'catalog_product.info',...);

vs.

$client->catalogProductInfo($sessionId, ...

It's never been clear to me how this improves .NET or Java compatibility (because I'm not familiar with those tool-chains).

Is this just a code generation convenience/culture thing, or is it literally impossible for .NET and Java users to use the original SOAP API?

Solution

  • What was the improvement in general?

    The building blocks of a SOAP service described by WSDL are roughly:

    • Contract: Specified by wsdl:portType, wsdl:message and wsdl:type, that describes operations as well as the messages and types these operate on. So this tells: What can the service do?

    • Binding: A wsdl:binding binds a wsdl:portType to a concrete transport, a document style, policies, etc. This tells: How to talk to the service?

    • Address: wsdl:service section links a wsdl:binding to an concrete service endpoint address. This answers: Where is the service?

    The above mentioned points are more or less the ABC-tenet of the Windows Communication Foundation (WCF).

    So the first RPC-approach of magento was simply an abuse of the SOAP protocol. Every request going through the key-hole of the few entry-functions has another, wrapped RPC protocol as message payload. So SOAP was just used as an message transport, just like SOAP uses eg. HTTP-POST. To keep the contract valid, it has to be either very complex (an enormous amount of possible messages) or very generic (simply a string). The contract becomes much easier if every method/operation has it's own declaration. That is what the V2 API does.

    But why is this also a big improvement for static typed languages like Java or C#?

    Like macki mentioned, there is tooling (proxy generators, etc) and frameworks (like WCF or JAX-WS) for these languages. They generate depending on the above mentioned contract data transfer objects (DTO)s for the message-types and proxies for the method invocation (they do much more but that's not important here). As you see in the Magento Wiki on C# magento soap v2 api an filters-object is instantiated and the salesOrderList proxy method. A good part of the contract is based on static typing of the method and its parameter. If you would use the V1 keyhole-methods you had to build the messages to satisfy the contract by yourself in an more arbitrary data structure like a string, array of strings or dictionary of strings.

    So of course it is possible to use the old API from static typed languages it doesn't feel right. It is much better to have on type per message-type and a statically typed signature of operation proxies. Beside that V2 are also better SOAP service regardless the language you call them with.