What Constitutes A Web Service?

The explosion of the concept of “web services” has generated a debate over what “web services” actually are. An article by Raj Mishra tries to limit the concept of “web service” to a strict ten-point list, insisting that a web service have a WSDL and uses SOAP. While this is a perfectly fine sentiment (even the one endorsed by WC3), it certainly is a limiting description.

The reality is that the definition of “web service” has grown, and Mr. Mishra’s list is both inaccurate and misleading.

While the W3C description defines a web service as using SOAP and having a WSDL, it also states that “There are many things that might be called “Web services” in the world at large. … without prejudice toward other definitions, we will use the following definition.” In other words, W3C’s definition is neither comprehensive nor exclusive.

Some of the world’s most popular web services no longer force use of WSDL or SOAP. Flickr, Twitter, Facebook and even Google allow access to their data and services without using SOAP, either by way of XML, REST, JSON-RPC or XML-RPC. And when the big players decide that their definition of “web service” includes these things, that really breaks any definition issues by anyone else.

So perhaps it’s time now for a new definition of “web service” starting. Here’s mine.

A web service is any service that meets the following criteria:

1. Provides an endpoint or endpoints for the retrieval and/or addition of data through a standard format; and
2. Contains one or more documented method(s) for retrieving or adding that data; and
3. Allows access by users who are not operating from the same servers as the endpoint(s).

How does a service like say, Twitter, follow these? First, it provides an endpoint for both the addition and retrieval of information (in XML and JSON). Second, it contains more than one documented method for doing so. Third, almost the whole point of Twitter is to access it from somewhere OTHER than the web – SMS, desktop applications, etc. Thus, Twitter would qualify as a web service, whether you use their WSDL or their REST API.

The reality is that as much as we might want to constrain concepts to a particular corner, the major players and the world at large will determine what qualifies as a “web service” and what does not. SOAP is one of many different ways to consume and access web services but it is by no means the sole way to do so. Limiting the concept of “web services” to a definition issued by W3C, who themselves acknowledge that there may be other “web services” that don’t fit their definition, just makes you look silly.

Brandon Savage is the author of Mastering Object Oriented PHP and Practical Design Patterns in PHP

Bradley Holt (@BradleyHolt) wrote at 7/15/2009 5:04 pm:

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

Brandon Savage (@brandonsavage) wrote at 7/15/2009 5:21 pm:

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.

Bradley Holt (@BradleyHolt) wrote at 7/15/2009 5:25 pm:

Brandon, that makes sense, thanks for clarifying!

Ray Paseur (@Ray_Paseur) wrote at 7/15/2009 6:49 pm:

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.

Larry Garfield (@Crell) wrote at 7/16/2009 2:01 am:

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. :-)

Copyright © 2023 by Brandon Savage. All rights reserved.