Comments on: What Constitutes A Web Service?

By: Larry Garfield

Larry Garfield — Thu, 16 Jul 2009 06:01:15 +0000

I will add one more requirement: The communication to and from those endpoints must take place over HTTP(S). That’s what makes a remote service a “web” service. Otherwise, your definition would include telnet and ssh as “web services”, since they provide end points with a documented interface for remote access. Remote data access is really old news. :-) Doing it mostly over ubiquitous HTTP is what makes it a “web” service specifically.

It’s worth noting that still means every web browser is really a web services client, and every web server a web services server, and every web page a web services response. Yes, that is in fact the case. :-)

By: Ray Paseur

Ray Paseur — Wed, 15 Jul 2009 22:49:19 +0000

I participate in Experts Exchange and answer questions in the PHP zone. A fairly common question goes something like this, “How come I can’t get SOAP to work…?” I have seen thousand of human hours wasted in confusion over the complexity of SOAP interfaces.

In contrast, I have NEVER seen someone get stumped by a RESTful interface. Flickr, Twitter, Facebook, Google, Yahoo – they all get it. Show any novice a single example, and they are off to the races. REST is better than SOAP, period.

So without putting my tongue too far into my cheek, let me suggest that a new category, perhaps called “Web Disservices,” should be defined. These would include the services that have confusing or incomplete documentation, change the interface without changing the URL, return malformed XML, are subject to timeouts, return ambiguous data, etc. I am sure the list could be more complete.

By: Bradley Holt

Bradley Holt — Wed, 15 Jul 2009 21:25:44 +0000

Brandon, that makes sense, thanks for clarifying!

By: Brandon Savage

Brandon Savage — Wed, 15 Jul 2009 21:21:20 +0000

Brad, you make a good point and I think my definition of “documented” needs some revision and explanation.

By “documented” I mean that there is a way for a developer or application to find the method. That documentation can take the form of online documentation, a WSDL, or as you describe here. In classifying web applications my goal was to exclude those that exist solely for internal purposes as being defined as web services (e.g. the internal Twitter API that is not subject to rate limits, etc.).

Since a web service is meant to be ingested, the methods you can use should be defined in some way, and documented in some way, even if their existence is not revealed until runtime.

Hope that provides some clarity.

By: Bradley Holt

Bradley Holt — Wed, 15 Jul 2009 21:04:05 +0000

Good blog post! I agree that the definitions put forth are too limiting. In following that thought process, I should point out a limitation in your definition of a web service ;-)

One of your requirements is: “Contains one or more documented method(s) for retrieving or adding that data”. I’ve been interested in the concept of HATEOAS (Hypermedia as the Engine of Application State) lately, which is one aspect of REST. Using HATEOAS, you don’t need to document your methods for retrieving or adding data ahead of time (in fact, it’s preferable that you *don’t* document these explicitly so that they can evolve over time). This documentation is “generated” (so to speak) at runtime in your hypermedia. You *do* document: 1) as few URIs to start with as possible (ideally just one), 2) your link relations (e.g. self, edit), and 3) your media types. The verbs are already known (i.e. GET, POST, PUT, DELETE) but you could document those too if you’d like to be clear. The article “Describing RESTful Applications” has a more in-depth explanation of this approach:

http://www.infoq.com/articles/subbu-allamaraju-rest