The Problem

Often, a remote procedure call (RPC) was used to design APIs, ensuring that, it seemed and felt as if the code was executed locally. In this way, APIs worked like functions. On the flipside, their transition to the Web became complex. The connection-less nature of HTTP compelled and forced developers to formulate an appropriate strategy.

Some technology stacks proposed a solution in which an RPC-like stack attempted to conceal the contents. While this trick did increase the speed for transferring applications to the Web, it posed another issue. Developers began engaging in inefficient code practices, resulting in low-quality code. Around this time, the idea of REST was floated via a paper.

How did REST solve the Problem?

Instead of relying on complex protocols such as SOAP, RPC, COM+, and CORBA, REST adopted a far simpler route; it used HTTP calls to communicate on an inter-machine level. REST made these calls message-based, where the HTTP protocol was needed to unlock the contents of these messages. Hence, REST is a simple, uncluttered architectural style that uses the request/response mechanism on the top of the HTTP protocol.

Anatomy of a Request

Requests consist of a body and a message. It tells the server to execute a task. A response is similar, except for the addition of another field: status code. A request in REST consists of the following four key components.

1. The Endpoint

Also known as the route, the endpoint is the requested URL. The format of an endpoint is as follows:

root-endpoint/?

The API’s starting point that is being requested is called the root-endpoint. For example, Twitter’s root-endpoint is https://api.twitter.com. The path searches for the requested resource.

2. Method

The method entails a request type that is sent to the server by the client. There are five request types - each of them is similar to the CRUD functionality.

· GET – It is used to fetch a resource from a server. It is similar to the READ operation.

· POST – It produces a new resource on a server. It is similar to the CREATE operation.

· PUT and PATCH – They update resources on a server. They are similar to the UPDATE operation.

· DELETE – Removes a resource from a server. It is similar to the DELETE operation.

3. Headers

Headers are a communication medium through which both server and client exchange information. Headers are useful for a variety of applications such as representing the information in the body content or being used for authentication. HTTP headers follow a property-value format wherein a colon separates them. In the following example, a header informs a server that it contains JSON content.

"Content-Type: application/json"

4. The Data

Also known as the message or body, data stores information that the client sends to the server. Except for the GET request, all other requests can send data. For example, if you use the command line utility cURL, you can send data with the following format where p1 and v1 represent the first property and first value respectively.

curl -X POST <URL> --data p1=v1

Why REST is used?

· REST offers scalability. Since there is separation of concerns between the server and client; developers can easily scale up different modules of the application. They can perform server migrations and modify the data – the only prerequisite is that each request sends data correctly. Because of this separation, developers can easily create both their front-end and back-end on different technologies.

· Since the client and server are separated, REST ensures that the UI is uncoupled from the data storage and server. In development, this can be quite handy. For instance, it enhances the interface’s portability with other platforms. Similarly, it also facilitates a project’s scalability.

· The detachment between server and client makes REST independent. You can use it with any language or platform. Thus, REST can adapt to any platform or syntax. You can use it with Node.js, Python, Java, PHP, C#, and other servers. However, you cannot change the language of the responses which is usually XML or JSON.

What makes REST so popular?

REST succeeds because it does not attempt to bind your API to the client-side technology. REST API can be accessible from various client-side technologies like an IoT device, an iOS/Android app, or a React/Angular front-end Web project. This is why it is widely used by companies without concerns over dependence on a specific client-side technology stack.

Additionally, bear in mind, that REST API ensures that the server is stateless and supports caching. Caching is necessary because if several requests are requested for the same resource, caching the request’s result means that the server’s scalability must increase.

On the other hand, statelessness ensures that any call that is made to the API is not tied with a specific server. In this way, developers can easily construct a scalable server infrastructure. The stateless server nature ensures that all the server calls are required to add complete data for executing requests.

manyos technology

If you need help regarding REST APIs for BMC Remedy, you can contact manyos. The company maintains strong reputation with regards to their knowledge and their development efforts over REST APIs, particularly how they integrated ticketing systems with their state-of-the-art APIs. You can look into their ITSM API which is used to link enterprise-level software BMC Remedy, SmartIT, and MyIT. Just recently, they added another feather to their cap with the release of a new product: SMILEconnect. SMILEconnect ensures that users do not have to engage in complex and time consuming customizations and can easily generate their integrations and interfaces.

BMCs Remedy ITSM platform is one of the most commonly used and mature Service Management Systems - but automating it can be tough.

In our previous blog post we got you started with flint's orchestration platform. In this post we'll show you how to query Remedy Forms, how to handle the response, how to create new records or how to update existing ones.

Let's take a typical integration use case: An external system is called on a regular base. Depending on the response, new records are created in Remedy or existing records are updated.

In our example we have a custom build Remedy Application. This application requires up-to-date exchange rates between EUR and USD. We'll poll an external Webservice to get the current exchange rate and we'll store them in a Custom Remedy Interface Form. We'll check the form for existing records and update them if necessary.

To get this example running you need a BMC Remedy Server and a running copy of Flint. You'll also need:

AR Restful API

A Restful API wrapper around the BMC Remedy Java API. For a quick start just run:

docker run -d -p 8080:8080 vipcon/arapi

on your docker environment. This will pull the latest Version from Docker Hub and deploy it in your environment.

Remedy Toolkit

Our Remedy Toolkit wraps up the AR Restful API calls and provides some basic call handling. We're going to provide a native Remedy connector in the near future. Contact us to get a copy.

Exchange Rate Webservice

We'll also make use of the Exchange Rate Webservice provided by Fixer.

Flint Configuration

In our example we'll use two different HTTP connectors. One for the Remedy connection and one for the Exchange Rate WebService call. You can get away with only one, but using two will give you more control about scalability and security. E.g. You might want to deploy the Remedy Connector on a separate Grid Node within your DMZ.

In our example the connector configuration is very basic and does not require anything else than the name.

We'll also use a Global Configuration for the Remedy connection. You can also provide these values with each request, but storing them only ones seems to be more appropriate.

Sample configuration for the Remedy connection

You can configure the following values:

arapi - The URL of your AR Restful API

connector - The name of the HTTP Connector that should be used.

username - The Login ID of the Remedy User that should be used.

password - The password of the Remedy User.

port - The port of the Remedy Server. If you use a Portmapper, enter 0.

server - The name or IP of the BMC Remedy AR Server

Remedy Interface Form

We'll use a very simple Remedy Interface Form to store the conversion rate of the day.

You can download the .def File of the Form here.

The Code / Workflow

For our interface we'll just need a simple Flintbit to query the Webservice and update the interface form.

First we'll get the current Exchange rates from Fixer.

//call the connector
def exchangeResponse=call.connector("Fixer")
         .set("method","get")
         .set("url",url)
         .set("timeout",15000)
         .sync()

This call will return something like this:

{  
   "base":"EUR",
   "date":"2016-02-15",
   "rates":{  
      "AUD":1.5624,
      "HRK":7.62,
      "USD":1.118,
      "ZAR":17.6114
   }
}

Based on the Run Date we can check the Remedy Interface form for existing records:

def query = "'Run Date' = \"${runDate}\""
def queryResponse = call.bit("remedy:base:query.groovy")
                  .set("form",interfaceForm) // Set arguments
                  .set("query", query)
                  .sync()

If we find existing entries, we'll update all of them:

queryResponse.data.each { myRecord ->
    log.debug "Update " + myRecord.getKey()
    def recordData = "{ \"${myRecord.getKey()}\": { \"Currency\": \"EUR -> USD\", \"Exchange Rate\":" + rate + ", \"Run Date\" : \"${runDate}\" } }"
    def updateResponse = call.bit("remedy:base:update.groovy")
                        .set("form",interfaceForm) // Set arguments
                        .set("data", recordData)
                        .async()
  }

For better performance on multiple entries we do the update asynchronously. Be careful if you do this for large number of records.

If we didn't find any existing records we'll create a new one:

def recordData = "{ \"MyRefId01\": { \"Currency\": \"EUR -> USD\", \"Exchange Rate\":" + rate + ", \"Run Date\" : \"${runDate}\" } }"
def createResponse = call.bit("remedy:base:create.groovy")
                      .set("form",interfaceForm) // Set arguments
                      .set("data", recordData)
                      .sync()

The full code looks like this:

import groovy.json.*

//build the url
def url="http://api.fixer.io/latest"
def targetRate = "USD"
def interfaceForm = "manyos:currency"

log.info "Query Fixer for latest Exchange Rates"

//call the connector
def exchangeResponse=call.connector("Fixer")
         .set("method","get")
         .set("url",url)
         .set("timeout",15000)
         .sync()

//get the response
def myBody = exchangeResponse.body

//Create a Object out of the JSON response
def jsonSlurper = new JsonSlurper()
def myRates = jsonSlurper.parseText(myBody)

log.info "Query Remedy for existing records"

//Get the actual Values
def rate = myRates.rates.USD
def runDate = myRates.date
def query = "'Run Date' = \"${runDate}\""

def queryResponse = call.bit("remedy:base:query.groovy")         // Provide path for flintbit
                  .set("form",interfaceForm) // Set arguments
                  .set("query", query)
                  .sync()

//Check if record for today already exists - if yes: update, if not: create
if (queryResponse.data.size() > 0) {
  log.info "Entry found for query: " + query + ". Update instead."
  //update all records
  queryResponse.data.each { myRecord ->
    log.debug "Update " + myRecord.getKey()
    def recordData = "{ \"${myRecord.getKey()}\": { \"Currency\": \"EUR -> USD\", \"Exchange Rate\":" + rate + ", \"Run Date\" : \"${runDate}\" } }"
    def updateResponse = call.bit("remedy:base:update.groovy")         // Provide path for flintbit
                        .set("form",interfaceForm) // Set arguments
                        .set("data", recordData)
                        .async()
  }
} else {
  log.info "Create new Record"
  //Create a new Record
  def recordData = "{ \"MyRefId01\": { \"Currency\": \"EUR -> USD\", \"Exchange Rate\":" + rate + ", \"Run Date\" : \"${runDate}\" } }"

  def createResponse = call.bit("remedy:base:create.groovy")         // Provide path for flintbit
                      .set("form",interfaceForm) // Set arguments
                      .set("data", recordData)
                      .sync()
}

You can download the code here.

Scheduling the Integration

To make sure that we'll always have the latest data, we'll let our integration run every hour. To do this we just need to place a schedules.conf in our FlintBox. To run hourly it should have the following content:

"my-schedule" {
  description = "runs our integration every hour"
  trigger = "ars:remedy.groovy"
  cron = "0 0 0/1 1/1 * ? *"
  enable = false
  input {
  }
}

Conclusion

Integrating an external system into BMC Remedy is simple and fast forward with flint. Using an orchestration tool like Flint make developing integrations a lot faster and easier. For a simple interface like this you now only need a few lines of code.

In the next post we'll look into ITSM Automation by Configuration with flint and our Service Management toolkit. We'll also start building our own cloud with Microservices, BMCs ITSM Suite, Flint and Docker.

1 Comment

Blog

Background: What Are REST APIs? Why Do We Use It?