RESTful debugging the relaxed way

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:

Notice that the url was split up into two parts, the Endpoint that is the hostname and the Resource, which is the path to the engine. The third part is parameters and is typically used in GET requests (see below for verbs), but we won't be using this field for now. Also notice the %20s in the Resource field were decoded to spaces! This is bad, and is a bug in SOAPUI, so your tool of choice might not have this issue.

/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.

Now it is time to check out our awesome new help documentation, specifically the POST event. We extrapolate from there and consider all our properties, carry the 1 and we come up with this as our payload:

{
      "properties": {
           "Carb Free": true,
           "Flavor": "pistachio blueberry",
            "Color": "Green Blue"
      },
      "recipients": [{
           "targetName": "tdepuy"
      }]
}

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!

Cool. So we've successfully set up SOAPUI to make calls to the xM REST web service which in essence allows us to actually simulate a management system. This can be very handy for debugging an issue: Is that property not showing up because the management system is doing something funky? Well, we can just simulate that system with a REST client such as SOAPUI.

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:

Highlight the entry in the "Bin URL" and copy to a safe place. Then head over to SOAPUI and update the package by adding a "callbacks" entry. For this example, we're just concerned with the responses but in other cases we might be more interested in the status or deliveryStatus callbacks, so, we just have one entry with the url as the url from requestb.in and set the type to response:

{
      "properties": {
           "Carb Free": true,
           "Flavor": "yogurt white chocolate chip",
            "Color": "White"
      },
      "recipients": [{
           "targetName": "tdepuy"
      }],
      "callbacks": [{
        "url": "http://requestb.in/wbhaq4wb",
        "type": "response"
      }]
}

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:

Sweet! We can see what xMod is sending along in a callback and in this case this crazy tdepuy guy actually wants a yogurt white chocolate muffin. Oookaaaaay. (By the way, I actually saw this muffin in my local coffee shop the other day... needless to say I opted for the strawberry scone instead.)

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.

Happy RESTing!

xMatters Reference

Blog- Originally created by Travis Depuy

Have more questions? Submit a request

8 Comments

  • 0
    Avatar
    Neil Dronet

    I got this successfully working in our non-prod environment, however I prod we are using SAML so as you probably guess I'm getting Kerberos Authentication Errors. I'm currently trying to find how to configure SoupUI to work with SAML, but figured I should ask here as well. Any assistance is appreciated as this is new ground for me.

  • 0
    Avatar
    Travis DePuy

    Hey Neil! Glad to hear you got it definitely mostly sorta got it working! :)
    Since web service users aren't "normal" users they typically aren't authenticated with the normal user authentication (in your case via SAML via your identity provider). So, the Engineer types have put in a "function" called "Enable Native Login For SAML Users". This allows the user to be authenticated Natively (i.e. from xM) instead of the external identity provider.
    I would create a new Role called "Web Service User" and associate the "Enable Native Login For SAML Users" function to that role, then grant the new "Web Service User" role to your REST user defined in SOAPUI.
    Make sense?

  • 0
    Avatar
    jsli

    I tried to follow the above steps using SoapUI to POST to one of my relevance engine form REST URL of my xmatter instance, but I get a page of the HTML source code containing the loginForm in the response. The following is what I had done:
    - Authentication: choose BASIC and filled in my username / password
    - Verified my username is granted form permissions in the Developer tab under respective relevance engine form.
    - Have tried using two options in Auth: Use Global Preference | Authenticate pre-emptively

    What steps is missing to get the expected result ?

  • 0
    Avatar
    jsli

    I found my problem - is because the form name or relevance engine name contains a blank space in URL, which Travis had mentioned the issue of SoapUI. Removed the blank spaces or use url encoding will resolve the issue.

  • 0
    Avatar
    Travis DePuy

    @jsli, yea that has tripped me up several times. I should add a screen shot to reiterate that.

  • 0
    Avatar
    Doug Peete

    @Neil and @jsli - congrats on hitting the REST API, it is always cool to see our customers using our latest integration tools.

    FWIW: it looks like our latest monthly feature release just went live in our shared environments and it introduces two new optional sections to our JSON form structure: priority and responses.

    Priority allows you to set the priority of the event so your user's device priority preferences will take effect.

    Responses allows for you to selectively choose the responses you would like your end user to see in their message so you can have variable responses depending on the current state of your business process. Check it out: https://help.xmatters.com/5.5.60/#xmodwelcome/relevanceenginebuilder/restapis/rest_postevent.htm%3FTocPath%3DBuild%2520relevance%2520engines%7CAppendix%253A%2520Relevance%2520engine%2520REST%2520API%7C_____7

  • 0
    Avatar
    Neil Dronet

    Travis - long time. I did get the restapi working with SAML. I had two issues, one was a bad password :) shocker I know! The other was I had spaces in the relevance engine like jsli. Encoded those and it all worked!

  • 0
    Avatar
    Travis DePuy

    Niel, thankfully there are times when it is just the simple things. That makes all those times when it isn't simple just a bit better because you remember the simple ones.... sometimes... after 4 or 5 head-desk moments.

Please sign in to leave a comment.
Powered by Zendesk