First up, there is no silver bullet in building a web service infrastructure. There are two prevailant types, however, that you should ideally be choosing from:
- RPC (remote procedure call) – e.g. SOAP, XML-RPC
- REST (Representational state transfer) – e.g. umm? REST?
What I strongly suggest is using one of these, and not designing your own protocol, or proprietry XML straight-up. As for which you should choose…
One thing you’ll notice when developing a REST web service is that there isn’t an exact specification of the protocol and structure, however the suggested way is to use discrete urls as resources, and use HTTP (GET, POST, PUT, DELETE) methods to determine the action to perform.
Looking at the Twitter API, it instead forgoes the discrete resource urls and HTTP methods in favour of using verbs in the url to determine the action to perform on the resource, and just HTTP GET and POST to determine whether it gets or sets data. This hasn’t stopped it from being successful however, and its use of “REST” standards has attributed to the success of many of its third-party sites.
Since the idea in REST is to use the HTTP specification in designing the implementation, there is only a small amount of error reporting that can be done using HTTP status codes, the HTTP methods may not be enough to represent complex actions, and the input protocol (application/www-form-urlencoded) is only a simple key-value structure (sure PHP improves on it with the use of  to represent multi-dimensional data, but not all servers and clients are written in PHP, so this should factor into your decision).
However, the HTTP specification includes extra features such as caching that the web service can be coded to benefit from.
As for RPC web services, I’ll stick to talking about SOAP as its better featured than others. This instead entirely uses HTTP POST on a single url (endpoint), and uses verbs that determine actions and parameters. Yes it can have multiple endpoints, but for simplicity just consider them as other web services.
This is a protocol with a fixed specification, which can be relied upon to be the same. Both the request and response are simliarly structured with a header and body. It even has a specification for error reporting. Once you’ve seen one SOAP service, you’ve seen them all (well not exactly, different vendors sadly sometimes have their own nuances).
So I’ve already mentioned that there is no silver bullet. Each may be better suited depending on the situation. But what situtation?
The simplist answer some may jump to conclusions is that SOAP should be used in inter-application communication and REST for third-parties. That may be mostly true.
Some points to consider:
- Where a language has support, SOAP is easier to consume, with a standardised interface that can allow a language to make calls via a proxy that acts as if it were a local call.
- Any web service written in REST could also be written in SOAP, however the reverse is not as easily done due to the restriction on request complexity of resources and single-dimensional data
- REST is only suitable for sending key -> value pairs as input due to the nature of its input protocol (application/www-form-urlencoded), and would need additional resource urls to represent multi-dimensional and batch data, meaning multiple calls to create, insert and commit as a single transaction, when SOAP can do that all in one call.
- REST is tied to HTTP over the web, however SOAP can be used in different transports. A bit moot however if you only ever need to create/consume web services.
- REST has additional transport specifications that can be used for caching and conditional gets. However SOAP can still code this into a RPC function, or a SOAP header.
- SOAP has additional specification extensions such as WSDL and WS-* (too many to list)
In all, I favour SOAP myself, but then all the web services I have coded so far I believe to be necissarly complex enough to justify it over REST. In PHP it is extremely easy to create and consume SOAP using SoapServer/SoapClient, and it automatically throws SOAP faults as Exceptions, which I wouldn’t want to live without.
I can see the attraction of REST due to it’s language support and most services using it support JSON. Zend Framework also makes it easy to reuse your controllers, which should already be in resource structure, for serving REST views.