BCmoney MobileTV

Rock-paper-scissors chart (Photo credit: Wikipedia)

So why SOAP? Well quite simply this was what I used back when I was first working through PHP and learning the hard way how to expose some server-side “business logic” as a Web Service. This was over a decade ago (late 2006 through 2007), and Google’s SOAP Search API had yet to be phased out, and was still one of the biggest reference implementations of SOA principles. In all truth I’d almost never use SOAP for creating Web Services from scratch anymore, but it does have a few minor advantages in niche cases thanks to ws-security, SAML integration, well-formed response guarantee via schema validation, contract-first development for more stability amongst separate inter-dependent departments/organizations, etc.

I decided to dust this example off simply to have a historical reference of traditional SOA while moving a number of legacy APIs I support to RESTful architecture (since REST is the clear winner and most APIs I need to work with today are REST based anyway).

So this example will serve as a useful tool to go back and review every now and then, especially if your consulting ever takes you to an enterprise gig that still uses legacy SOA technologies (and yes despite REST taking over 6 years ago followed shortly by JSON replacing XML, there are still a decent amount of SOAP-based WS deployments out there at big companies, the kind of big enterprises with big budgets at stake and/or political reasons to keep their legacy technology stacks running). REST/JSON may have won the internet thanks to its simplicity, but there’s something to be said about what the various organizations that came up with SOAP and the ws-* stack had in mind (aside from complexity and lucrative implementation contracts/tooling sales), namely robustness and predictability. Take Netflix and YouTube for example, two of the most frequently called APIs on the web, both “RESTful-ish” but each taking their own liberties with Fielding’s original REST thesis in unique ways, particularly around Auth mechanisms and Usage Policies required to work with the data, DRM, Advertising, somewhat creative usage-restricting API metering, and/or pay-per-use schemes that come into play as soon as you want to do anything serious with the data, and both have suffered their developer communities significant amounts of non-backwards-compatible disruptive versioning, changes and feature deprecation.

Endpoint
The following enpoint is where you can make requests to initiate and get responses from specific operations being exposed by the SOAP Web Service:
http://bcmoney-mobiletv.com/widgets/games/rps/soap

In our case just a ServerTime check, GameScore check, GamePlay to initiate a game (but lots of other operations could potentially be added to this such as Leaderboard tracking by username or region, Multiplayer game listings to show available competitors, etc).

Web Service Description Language (WSDL)
This is the “contract” part of SOAP that tells SOAP clients how to interact with our Web Service. In general, you can reach the WSDL of a SOAP-based Web Service:
http://bcmoney-mobiletv.com/widgets/games/rps/soap?wsdl

A useful tool for validating your WSDL is the W3C WSDL Validator service.

XML Schema (XSD)
I’m a big fan of keeping the same basic format between requests and responses rather than many Web Services out there with vastly different request and response formats. This just creates unnecessary work writing (or annotating/generating) distinct XML parsers.

Request format:

 <rps>
  <game id="1234">
    <player id="1234#p1">
      <choice>PAPER</choice>
    </player>
    <player id="1234#p2">
      <choice="SCISSORS</choice>
    </player>
   </game>
 </rps>

Response format:

<rps>
    <game id="1234">
        <player id="1234#p1" outcome="WON">
            <wins>5</wins>
            <losses>4</losses>
            <draws>2</draws>
        </player>
        <player id="1234#p2" outcome="LOST">
            <wins>4</wins>
            <losses>5</losses>
            <draws>2</draws>
        </player>
    </game>
</rps>

Notice how only the data underneath the player element changes between request and response, and the two formats are virtually identical.

For more easily visualizing WSDL’s available operations and the data formats within each operation’s response check out the XML Grid – XSD/WSDL Viewer service.

Check some of the classic SOAP API examples that are still around today including Amazon’s Product Adveristing API (WSDL) which I’ve previously used as a product data source in my XmasListz Facebook App or the WebServiceX Currency Exchange API (WSDL) which was used in my post on how to work with SOAP in JavaScript & jQuery.

See the other parts here:

• Part 1: Creating a basic Rock Paper Scissors game in PHP
• Part 2: Moving a command-line PHP Rock Paper Scissors game to the Browser
• Part 3: Exposing your PHP Rock Paper Scissors game via SOAP Web Services <– you are here
• Part 4: Integrate PHP based SOAP RPS game server in another language, JAVA desktop GUI