Share:|

Version 9 is released and with it come some new features. Don’t worry, I’m not planning to list everything that’s changed, but I’d like to have a look at one specific new feature: the REST API. Web APIs are great, they allow you to interact with the system. I know that acronym is a little overused these days, but you’re using APIs all the time. If you open tripadvisor it shows a Google map with nearby restaurants, if you buy a product of Amazon you can proudly share your purchase with your friends on Facebook. That’s being done via APIs: Google exposes specific program functions that allow a developer of a different website (like tripadvisor) to interact with this.  So rather than having to build your own map application you just plug in and use Google’s.

 

Remedy is already providing APIs. If you want to write your own Java-based application, you can use the Java API. Remember I previously wrote about SOAP-based web services and used the book publisher as an example? That’s another way of interacting with the system.  Now there’s a new way of doing this: RESTful web services.

 

I know, we just love acronyms in web development, the cleverer the better. REST has been around for a while. I could probably spend the better part of this article talking about it, but let’s just say that it’s a design concept for managing state information. Yes, that still sounds theoretical, but bear with me here. What I mean by this is that it’s a way of making it easier for people to understand what’s happening (focusing on readability) and still making sure applications are able to work together efficiently. It gets more interesting when you talk about RESTful which typically refers to web services implementing this architecture.  All communication is done via common HTTP methods (GET, POST, PUT, etc.) and everything is accessed via a standard URL. Think of the HTTP methods as the verbs and the information you access as the noun, so you GET /books or you GET /books/{isbn}. If you want to remove a book you DELETE /books/{isbn}. POST /books creates a new one and PUT /books/{isbn} updates it. Depending on the web service you could define GET /books/{isbn}/author to get the author of the book.  As long as it’s readable.

 

So let’s have a look at the Remedy integration of REST. How does this work exactly? You need to communicate via an URL of course. We don’t use Mid-Tier, but instead use a JSP engine called Jetty which allows you to interact with the system. It’s installed by default, but you might need to turn it on. I’ve included a knowledge article below with steps. Once that’s done, it’s really just a matter of sending HTTP requests and processing the answers.

 

You’re probably wondering if that isn’t exactly what SOAP-based web services are doing. You create a SOAP envelope and send it via URL and you get the data back. That’s a good point, but here’s the difference: you don’t have to define a web service in Developer Studio. Every form can be accessed via a RESTful web service by default, you don't have to do anything special. Also, it’s a lot simpler. No complex web service definition and no SOAP envelopes. It’s light weight, both in defining the various requests and responses, and the amount of data that’s being sent up and down. Of course, you need to be familiar with the format of the requests and responses, but the principle is fairly straight forward: create a HTTP request, define the data you’re after and send it off. That’s where the main strength lies: it’s a lot easier to use from a programming perspective.

 

Still not sure? Let’s do a quick test. Get your version 9 box and set up Jetty. Chrome has some great plugins that can help us here, the one we use is called POSTman, but if you want to use Fiddler, that will work as well. The first thing we need to do is authenticate. For security reasons we need a token which included in all the requests during the session. Here’s what my request looks like in POSTMan:

 

s1.png

 

Notice the URL, it’s in a specific format and it’s using POST. Here’s what it looks like when it goes out on HTTP level:

 

s2.png

 

What I get back is an authorisation code which I can use of all the requests during the session. Next, let’s get all the records from the same form Sample:Cities. Here’s how we do this in POSTMan:

 

s3.png

 

Notice again the URL and request method.  We’re very specific here: we’re GETting data from /entry/{form name}. What we get back is in the JSON format (another acronym) which is easy enough to read. Next, I want to modify a record. Here’s my request:

 

s5.png

 

I’m using a different HTTP method, because now I’m PUTting /entry/{form name}/{id}. See, that the HTTP methods are used more intuitively (where possible of course)? Don't forget to close the connection again, here's how we do this:

 

s6.png

 

I hope you agree that it’s relatively straightforward to interact with the system this way. HTTP methods are used in such a way that it’s quite readable and overall the interaction with the system makes more sense. GET is used to retrieve data, POST to add and PUT to update. Sort of makes sense, doesn't it?

 

The data you get back is in JSON format. We don’t give you a choice here, XML is not possible. Personally I don’t have a preference, but in general the JSON format is more compact and tends to be more readable. But in the end you still have to process it, it all comes down to your own preference.

 

Let’s move away from POSTMan or Fiddler and put together a real life example to see how this works. Let’s write a small JavaScript-based example that gets data from a form and populates an HTML table. To make it a bit more interesting we’ll get the data without reloading the form (similar to the way Mid-Tier retrieves data). This is what I want:

 

example.png

 

I’m using JavaScript to handle the HTTP communication and to get the data back to the table. You can of course use a number of clients, but I believe a JavaScript-based application is the most likely implementation. Like our example, the first thing I need to do is write a function to retrieve the authorisation code. I use the XMLHttpRequest object to create the request. I make sure it’s a POST request, I set the right headers and finally I send it off with the POST data (the username and password fields). Now I’ll have to wait for the answer. I know it’s successful if the server responds with HTTP200, which means everything went fine, so that’s what I’m looking for. When I get it I return the data.

 

s7.png

 

I hope that makes sense. If you’re not that familiar with JavaScript just check how I’m communicating with the server. The XMLHttpRequest allows me to make the call and to handle the answer; there’s a specific way of having to do this, which is what you can see here.

 

I’m going to write a second function to get the records from the form. Like our example with POSTMan, we first need to get the auhorisation code and then send another request to retrieve the data. What I want to send is:

 

s8.png

 

My function is going to be similar to the one I used for the authorisation code, but now I’m sending a GET request.

 

s9.png

 

That’s the first bit. Same object, I tell it I want to use GET, I specify the URL and I send it off. I’m using a slightly different way this time to wait for the answer. In the first function I’m using the synchronous method which means nothing else can happen until the answer is in. Now I’m doing it asynchronous, which means that I allow other code to execute while I wait for the answer. It’s just to ensure the browser doesn’t go into a hanging state.

 

So when it’s ready (the readyState) and the HTTP status code is 200 I know I got my answer and I go ahead and process the data. I need to inform the server first that I’m ready to close the connection, but as this is similar to the first function, I won’t describe this.

 

We’re done now with the HTTP communication for the moment. I got my answer and I can start processing it. I mentioned before this is all in a format called JSON. Our form results in a specific format and you need to be familiar how it’s put together. This is the raw data:

 

s10.png

 

Sort of readable, but far fromideal. Let’s put it in a schematic overview using a JSON reader:

 

s11.png

 

It basically consists of a series of objects, arrays and elements. Arrays are defined with square brackets ([]), objects use curly brackets ({}). So in our case Entries is the first array which contains a series of objects for each entry (0, 1, 2, etc.). This object contains another two objects, one called values, another one called _links.

 

The data you get back for a form will always look like this. You need to come up with a way to interpret this. Here’s how I did this.

 

s12.png

 

There are other ways of doing this, but let me explain what I’m doing here. First things first, I need to parse the data via JSON.parse. This leaves me with an object I call jsonData. I know the array I want is called Entries so I create an array to just get this data. Next I need to loop through that array to get the various entries, that’s what I’m doing via that first for loop. I know each entry contains two objects and I use the second for loop in combination with the if to extract only the object called values. Once I’m here I have the right row.

 

Tricky isn’t it? You get used to it. The good thing about JSON is it integrates quite well with JavaScript. Once I have the data I can just write it to the screen and put together a table. I won’t go into this, but I’ve put together a complete example which you’re happy to use. In this example I extended the test case by populating a table. I’ve added comments to explain what I’m doing exactly.

 

The REST API lends itself well to integration via JavaScript, but as all we need is to send and receive HTTP requests which are relatively easy, it’s of course possible to use whatever programming language you prefer. I can write a similar application in Java, for example. The RESTful web service offers a good alternative to the already existing SOAP-based web services and the JAVA API, and exposing data and functionality this way will make it easier for the system to integrate with other applications. I think integration on web application level is probably the more obvious choice, but I'm interested to hear how it's being used and what the challenges are. I REST my  case (pun firmly intended).

 

Until next time,

 

blogname.png

Don't forget to follow me on twitter!

 

Note: When using a web application with REST API as in this example, be sure to configure the server to allow requests from specific domains to allow communication with Jetty. See knowledge article KA426025 for more details.

 

If you want to read more about version 9, check out the Remedy ITSM community.

 

 

Further reading: