I was just surfing quasi-randomly tonight and I came across the site programmableweb.com.  Very neat concept.  They are a reference site for various web services available on the Internet.  I was in a writin’ mood, so I thought I’d start a series on how to talk to web services using PowerShell.  The first example will be the UrbanDictionary.com SOAP API as described here and here.

If you are not familiar with the term, by “web service”, I mean a programmatic interface to something which can be reached over the Internet (or a private network), usually via HTTP or HTTPS.  One example might be a weather service.  Say you want to include a weather forecast on your website.  Rather than having a script go to a webpage and plugging in a zip code, then “scraping” the results and try to parse them in your program, what you do is use a connector or library for your language of choice which can speak the protocol that the web service uses.  Some web service protocol examples are: SOAP, XML-RPC, REST, or JSON.  (I just realized, so is WMI + WS-MGMT aka WinRM on Windows…)  You wave your hands over the hat, plug in the web service’s URL, give it a zipcode parameter, and you magically get back the forecast in a nice and tidy bundle of properties to an object, something you can manipulate natively in your program.

That’s your one paragraph web service intro.  Now, on to the tutorial!

1. Step numero uno: Read Keith Hill’s “Calling a Web Service from PowerShell” article.   He explains how to setup your environment, bind a web service, compile that to a DLL, load the DLL in PowerShell and instantiate an object which represents your brand new web service. 

   (Ok, I’m cheating a little (lot)–Keith’s done most of the work for me here.  But it’s all about the applications, right?)

2. Go to UrbanDictionary’s API page and request an API key.  Find it in your email and go to the next step.
3. Follow Keith’s steps, plugging in the web service URL (easily found at programmableweb’s listing for UrbanDictionary).  It looks like this:
   

      1: wsdl http://api.urbandictionary.com/soap?wsdl

      2: csc /t:library .\UrbanSearch.cs

      3: [reflection.assembly]::LoadFrom( "$pwd\UrbanSearch.dll" )

      4: $urbandicsvc = New-Object UrbanSearch

4. Now, the $urbandicsvc object holds magical treasures such as Lookup().

      1: $urbandicsvc | gm lookup

      2:    TypeName: UrbanSearch

      3: Name   MemberType Definition

      4: ----   ---------- ----------

      5: lookup Method     Definition[] lookup(String key, String term)

5. Now you find that key from your email and supply it to the Lookup method, along with a term you’d like to lookup.

      1: $key = '<your key goes here>'

      2: $urbandicsvc.lookup($key,"fo shizzle")

      3:  

      4: Exception calling "lookup" with "2" argument(s): "Invalid key"

      5: At line:1 char:20

      6: + $urbandicsvc.lookup <<<< ($key,"fo shizzle")

Hmmph.  That’s when I read this little gem from the email I received with the key:

Please also note that your key may not become active until 10PM Pacific. We apologize for the delay.

Oh well, maybe tomorrow, I’m East Coast! 

Let me know if you find this sort of article useful, and I’ll write more.

Update - Feb 10th @ 11:40am

Seems I picked a bad first example–I can’t get the service to work, and the developer wiki on urbandictionary.com seems to be defunct.  Maybe they no longer provide the service.