Working with web services can be tricky. Sometimes you don't really know what you need to send and you have no idea what you'll get back. Some vendors put a lot of "fun" in tracking down the API documentation, and by fun I mean like trying to find your contact lens in the ocean after you got a face full of wave... the salt water... it burns. However, regardless of documentation state, the web service will always accept or reject your request and will usually give you a helpful response in exchange.
In this post, I'll dive deep into making calls to the xM REST web services and we'll even get to inspect the callbacks!
Like any good codesmith, we need some good tools. My tool of choice for this kind of thing is SOAPUI. "But wait, you set us up to talk about REST web services and you're using a SOAP tool! How dare you mislead us, we will sign you up for cat facts." "Woah cowboy, SOAPUI does both!" As of some version ago (at least 4.6) a smart bear introduced REST functionality. There are a handful of other tools out there such as Google's Rest Client and others. I prefer SOAPUI because it can also interact with SOAP web services, so it saves me from having two different tools. All the functionality discussed here should reside in any respectable rest client so use what works for you.
Anyway, enough fluff, let's get down to muffins. We are going to simulate an integration service to the Muffin Readiness Engine! This engine will notify us when fresh muffins are ready at "Ye Olde Tyme Bake Shoppe".
I've created a few properties and added them to the layout and set Jaster.Mereel with permissions to call the web service.
Sweet, all set up to play! Grab the Web Service URL (in xM UI > developer > Manage Relevance Engines > On the appropriate engine > Forms > Select form > Access Web Service URL) and crack open SOAPUI and hit File > New REST Project. Then paste in the url we just copied and hit OK. This will create a new Project and show us the stubs:
/reapi/2013-12-01/engines/TD Test/Muffins Ready/events
Replace the spaces with a %20 or the web service will get really confused about where you want to send the request.
If you don't make that replacement, you'll probably crash the application, break the salt shaker or get this when you send the request:
This is just xMatters trying to redirect you to the login page because it doesn't know where you want to go.
A couple of things to set up first, Authorization and Method. Click the Auth button in the lower left corner. Enter the Username, Password and set the Authentication Type to Preemptive: (In some tools, Preemptive might not be available, but there should be something like "Basic")
Then just hit the Auth button again to hide that widget. The Method drop down in the upper left corner is the HTTP Verb we are using to interact with the Web Service: GET is typically queries, PUT is updates, and POST is add. So change the Method to POST. Once you change the Method, a new widget appears that holds the "payload" or "body" of our request. This is where we put stuff in.
"Carb Free": true,
"Flavor": "pistachio blueberry",
"Color": "Green Blue"
So, paste it into the payload widget in SOAPUI and hit the Play! button in the upper left corner and imagine the little json fairies transporting your little payload off to the xMod gods who will in turn send you a response. A moment later and voila!
And, if you have a user "tdepuy" who has an email device set up, you get a little something extra!
But wait! There's more. We can also simulate the management system receiving a callback with SOAPUI! We can even have it toast bread and make julienne fries. Well, ok maybe not. But there is another tool that will let us receive the callbacks and we don't even have to poke holes in our fire wall. You're on your own for toasting bread and julienne fries.
Introducing Requestb.in. Often pronounced "Request Bin", but I'll accept "Requestb in" and "whatever". This is a very handy website as it allows for inspecting anything thrown at it. So we could throw a SOAP message, a standard HTTP POST or GET and inspect what we sent to it. This alleviates any need to dig into log files, or open tickets just to see what you are sending to a web server.
Well, Ye Olde Tyme Bake Shoppe has exploded in popularity since we paired xMod with Muffins and we only have so much room to bake so many muffins. So, we're going to introduce a Muffin Reservation callback. Oooooooo, Ahhhhhhh. We could go learn Node.js or Ruby or JSP and whip up some cool web service to listen for these callbacks and act on them, but we'll leave that up to others. For now, let's just see what the REST API callbacks are sending.
While I was typing that last sentence, I had my little blue assistants add in the response options. Look what a great job they did!
Next, fire up your favorite web browser and point it over to http://requestb.in/. I know, the page can be a little intimidating, but just take a breath and check out the large, friendly letters on the big green button and click your mouse there. This displays a helpful page letting us know how to make requests in various languages:
"Carb Free": true,
"Flavor": "yogurt white chocolate chip",
Then pass off our new package to the json fairies with the Play! button and the xMod gods will respond, but in this case we are more interested in Requestb.in. So, track down the email that was sent and click "I want one!"
Then just hit the refresh in Requestb.in and hopefully you'll see something like this:
I hope our time together was useful and therapeutic for you. It sure was for me and my little blue assistants. Next time you are trying to figure out why something isn't getting into xMod or you're just testing a format, break out your favorite REST client and point it to your form web service. Or if your management system is freaking out because it can't find the Incident ID, crack open Requestb.in and inspect the callbacks and see if xMod is actually sending it over.
Blog- Originally created by Travis Depuy