The Linguistics of Webservices

It is frequently recommended that, readable/”good code,” should closely resemble speech. For example name a variable representing a collection “library” and a method “remove.” From those two items one can have the library remove a book. For example:

 
library.remove(book);

Services, in an odd situation, are meant to hide the client from the actual networking background, but yet be treated as the neighboring code within the application. Without the proxies and similar method calls, one should just write their own protocol and avoid using webservice. Therefore, I thought it would be a little interesting to do a thought experiment on how one can reference web services.

REST Services ask two basic questions “Can you _____ for me?” and “What do you know about ______?” The subject “you” in this case is a reference to the webservice. “Me” is the service client. Asking if the service can do something for you is referring to REST calls with the POST, DELETE, or PUT action code. Asking for something from the REST service is hinting at the GET [and sometimes post] HTTP action code will be used.  With REST running over HTTP all information has to be in Base64 encoding, meaning that there is only one encoding send to the receiving webservice.

SOAP is a little more complex. Scratch that it is a lot more complex. When SOAP was created, the deciding power to be went a little overboard for 90%* of the use cases. SOAP includes information about how the webservice is composed, structure of complex data types, error handling, and the calls themselves. Therefore, there should be a new way to refer to them. Web services can be asked the following questions:

  1. What can you do?
  2. What is that weird data type that is being returned by this method?
  3. What exceptions can be expected from this method?
  4. Can you run _____ [method]?
  5. Can we keep a secret? If so, then please run this privately _______. [WS-Security]
  6. Can you return/receive the results from [method] in another language? [WS-DIME]

Given any extra extensions to the WS-* specification, more questions may be asked.

* Statistics here are not an accurate measure, more of a wild guess. Nevertheless, it sounds right, that what counts, right?

  • http://antipaucity.com Warren

    I think that one of the great examples of this in the [common] .htaccess / mod_rewrite add-on to wordpress that allows for “human readable” URLs (domain/date/title)

    Then you have WSJ article links like http://online.wsj.com/article/SB10001424052702303343404577518942892486750.html

    Seriously, Wall Street Journal? Yeah, I suppose it’s unique …  but, dang! That’s not something you can read over the phone!

    All websites and webapps should structure themselves so you can relate to them in a RESTful manner – and that RESTfulness should be simple to grok, even as a non-developer.

  • Pingback: antipaucity – restful webservices()