This post was very informative. Enjoyed reading it. Is it possible to expose the same method in SOAP, JSON-RPC and XML-RPC. I develop in .NET where you decorate the method with [WebMethod] to expose it in a web service. Is it possible to expose the same web service and the methods inside in SOAP, JSON-RPC and XML-RPC. If it is not possible should the methods be duplicated three times to be exposed in SOAP, JSON-RPC and XML-RPC?

Thank You,
Vish
http://viswaug.wordpress.com

Thanks

To answer your other questions:

* No, the responses of our methods aren’t very cacheable. To start out with, it’s personal data. We have a quarter of a billion users. Unless you have a cache set up for a pretty small subset, your hit ratio is going to be pretty miserable. Additionally, given our inbound delivery rates, your mailbox is probably updating quite frequently, making message bodies one of the few pieces of data that aren’t constantly updating. The actual benefit of caching is probably pretty low.

* As for error messages, it depends on how basic you’re talking. You can easily distinguish success from error by checking for HTTP 200 vs. !200. If you want more detail than that, then you have to parse the response. The response will indicate who’s fault it was (yours or mine) and what the underlying error code is.

* Additions of optional parameters to the methods won’t break existing clients. Every method takes exactly one parameter. The parameter has numerous properties that indicate some facet of the execution of the method.

* No, you can’t point a browser at the service and see something useful (unless you consider a “hey, where’s my parameters” message useful).

I’m fully aware of the benefits of REST and sticking to HTTP as a protocol instead of using it merely as a transport. There were some conscious decisions that sent us down this road. Realize that this is the service we had to build internally to support the Oddpost acquisition, so we weren’t exactly building from scratch.

I would love to see the community reach out and collectively tell us that they want REST. If I can get that kind of weight behind such a request, then it makes my job of selling it internally that much easier. I’d love to see us make a REST offering available.

When talking of efficiency, are the responses of your getter methods transparently cacheable on the web? To understand an basic error message do you still have to parse the body of the message? If you decide to make a minor change to the method signature of one of your endpoints, would that break all existing clients? At a simple pragmatic level, can I point a web browser at the interface and see something useful? Can I post data into the system from a HTML form?

If the answer to any of these questions is no, I suggest checking out Paul Downey’s Good Web APIs are just Web Sites and Mark Baker’s Protocol Independence diagram.