Getting Started with APIs

Introduction

Overview

OpsRamp provides REST APIs to:

1. Get information about managed resources from OpsRamp.

2. Send information about managed resources to OpsRamp.

3. Configure OpsRamp to take management actions.

Authentication

OpsRamp APIs use OAuth 2.0 based authentication.

API URL

OpsRamp supports the following API URLs:

For Partner Users:

• If partner is custom branded, use partner custom branded API URL – https://<partner_name>.api.opsramp.com. For example, if partner name is Alpha, provide https://alpha.api.opsramp.com as the API URL.

• If partner is NOT custom branded, use https://api.opsramp.com as the API URL.

For Client Users:

• If client and partner are custom branded, use client custom branded API URL – https://<client_name>.api.opsramp.com. For example, if client name is Logix, provide https://logix.api.opsramp.com as the API URL.

• If client is custom branded, but partner is NOT custom branded, use https://api.opsramp.com as the API URL.

Each API request has the following header format:

Header	Value
Accept	application/json
Content-Type	application/json
Authorization	Bearer {accessToken} or Basic base64_encode(loginName:password)

API Request Throttling

API throttling limits the number of requests an API server accepts within a time period. The API server rejects requests that exceed the limit and will return 429 Too Many Requests status code.

OpsRamp throttles API requests to ensure a better quality of service. The following limits apply for each tenant (service provider, partner, and client). API requests made after a throttling limit will fail with a 429 status code error.

Throttling Limits

API Category	GET (non-paginated) (requests/minute)	GET (paginated) (requests/minute)	POST/DELETE/PUT (requests/minute)
Alerts	500	50	200
Metric	500	50	5000
Device	500	50	25
Tickets	500	50	50
Other APIs	500	50	50

Note: The API rate limits may change to ensure better performance and service, hence it is advisable to use HTTP headers while making API requests.

Response headers include usage against limits

API response headers include information on usage against throttling limits so that application making API request can self-regulate their requests.

HTTP Header	Description	Example
X-RateLimit-Limit	Number of requests the user is allowed to make per minute.	X-RateLimit-Limit: 500
X-RateLimit-Remaining	Number of requests remaining in the current rate limit window.	X-RateLimit-Remaining: 14
X-RateLimit-Reset	The time at which the current rate limit window resets. Time in UTC epoch seconds.	X-RateLimit-Reset: 1491397260

Sample Error Response

Below is the sample response generated if the API requests exceed the rate limit.

{
	"error" : "throttled",
	"error_description" : "Too Many Requests"
}

Return Status Codes

Each API call returns one of the following return codes.

Status	Message	Details
200	Success	The request has succeeded.
400	Bad Request	Unable to authenticate.
401	Unauthorized	The system/user is not authorized to use the API.
404	Not found	The requested resource was not found.
405	Method not allowed	The HTTP action is not allowed for the requested REST API, or it is not supported by any API.
407	Proxy Authentication Required	Token is expired.
410	Gone	Tenant is unavailable or deactivated.
429	Too Many Requests	API rate limit is reached and request made after the rate limit fails.
500	Internal Server Error	The server encountered an unexpected condition which prevented it from fulfilling the request.

Generate API Requests

Prior to initiating an API request install the integration, obtain the access token and then generate the API request.

Step 1: Install Integration

• This integration is the channel through which the API communicates with OpsRamp.

• Each integration has an OAuth Key and Secret, which is used to obtain an OAuth Access Token.

Step 2: Generate an Access Token

1. Prior to making API requests, obtain an access token using the OAuth Key and Secret.

2. Steps to obtain OAuth Key and Secret.

   1. Click Setup.

   2. Click Integrations on the left-hand side panel and then click Integrations. Integrations page appears.

   3. Click Available Integrations and then click on the required integration.

   4. Click Install to install the integration.

   5. Select authentication type OAUTH2 and then click Save.

   6. Capture the Key and Secret for the integration.

3. Authenticate with OpsRamp using auth API as below

   • Curl

     curl -k https://<api-url>/auth/oauth/token -H "Content-Type: application/x-www-form-urlencoded" -H "Accept: application/json" -d "grant_type=client_credentials&client_id=QSVGpk9u9YB6u7NhXCavBeFJhY68dcDt&client_secret=TSXd9h35ZDEWGs6YAgf9338MjTJ8cX97VkaKk2aanzaKrz5V9wC8xBk63EqECmV7" -X POST

   • Python

     import os, sys, json, time, base64
     import urllib2
     
     is_urllib_request = False
     try:
         # For Python 3.0 and later
         from urllib.request import urlopen, install_opener, build_opener, Request, HTTPBasicAuthHandler
         from urllib.error import HTTPError, URLError
         from urllib.parse import urlencode
         is_urllib_request = True
     except ImportError:
         # Fall back to Python 2's urllib2
         from urllib import urlencode
         from urllib2 import urlopen, install_opener, build_opener, Request, HTTPBasicAuthHandler, HTTPError, URLError
     
     config_json = {
         'server'    : 'api.opsramp.com',
         'api_key'   : 'API_KEY',
         'api_secret': 'API_SECRET',
         'client_id' : 'CLIENT_ID'
     }
     TIMEOUT = 120
     config  = None
     
     class OpsRampConfiguration:
     
         def __init__(self, config_json):
             self.server     = config_json['server']
             self.api_key    = config_json['api_key']
             self.api_secret = config_json['api_secret']
             self.client_id  = config_json['client_id']
     
     
     def init_config(config_json):
         global config
         config = OpsRampConfiguration(config_json)
     
     
     ''' Generic HTTP GET/POST method '''
     def httpPost(url, headers={}, data=None, user=None, passwd=None):
         try: 
             http_headers = {
                 'Content-Type' : 'application/json',
                 'Accept'       : '*/*'
             }
             http_headers.update(headers)
             req = Request(url, data, http_headers)
             if user and passwd:
                 authhandler = HTTPBasicAuthHandler()
                 authhandler.add_password(None, url, user, passwd)
                 install_opener(build_opener(authhandler))
     
             return urlopen(req, timeout=TIMEOUT).read()
         except HTTPError as emsg:
             if emsg.getcode() == 500:
                 return emsg.read()
             else:
                 print emsg.read()
                 raise Exception(emsg)
         except URLError as emsg:
             raise Exception(emsg.reason)
         except:
             raise
     
     
     ''' Get opsramp access token using api key/secret for further communication '''
     def get_access_token():
         url = "https://%s/auth/oauth/token" % (config.server)
         print url
         print config.api_key
         print config.api_secret
         print config.client_id
     
         data = urlencode({
             "client_id"     : config.api_key,
             "client_secret" : config.api_secret,
             "grant_type"    : "client_credentials"
         })
         if is_urllib_request:
             data = data.encode()
     
         headers = {"Content-Type": "application/x-www-form-urlencoded", "Accept" : "application/json"}
         try:
             result = json.loads(httpPost(url, headers, data))
             config.access_token = result['access_token']
         except Exception as emsg:
             raise Exception("Error while getting access token - " + str(emsg))
     
     if __name__ == '__main__':
         try:
             init_config(config_json)
             get_access_token()
             print config.access_token
         except Exception as e:
             print ("main function failed - " + str(e))

   • Java

     package com.opsramp.examples.rest;
     
     import java.io.IOException;
     import java.nio.charset.StandardCharsets;
     import java.util.ArrayList;
     import java.util.List;
     
     import org.apache.http.HttpException;
     import org.apache.http.HttpHeaders;
     import org.apache.http.client.entity.UrlEncodedFormEntity;
     import org.apache.http.client.methods.CloseableHttpResponse;
     import org.apache.http.client.methods.HttpPost;
     import org.apache.http.entity.ContentType;
     import org.apache.http.impl.client.CloseableHttpClient;
     import org.apache.http.impl.client.HttpClients;
     import org.apache.http.message.BasicNameValuePair;
     import org.apache.http.util.EntityUtils;
     
     import com.google.gson.JsonElement;
     import com.google.gson.JsonParser;
     
     /**
      * Sample program to fetch access token from token end point
      */
     public class GetAccessToken {
     	
     	/**
     	 * Main program which invokes get access token request
     	 * @param args
     	 * @throws IOException
     	 * @throws HttpException
     	 */
     	public static void main(String[] args) throws IOException, HttpException {
     		//Replace the token end point, api key and secrets accordingly
     		String TOKEN_ENDPOINT = "https://<api-url>/auth/oauth/token";
     		String API_KEY = "AFBS9BkX72PYsgQn9GvJKUquDQnRuSKD";
     		String API_SECRET = "6MqBTZK9DUTVREECrVQV2UEtGub2uGfvY4zq252GKTE4BWNCEXN9HJW3u3cQR8Nn";
     		
     		//Performing access token request
     		String response = invokeTokenRequest(TOKEN_ENDPOINT, API_KEY, API_SECRET);
     		System.out.println(response);
     		
     		String accessToken = null;
     		if(response != null && !response.isEmpty()) {
     			JsonElement json = new JsonParser().parse(response);
     			JsonElement token = json.getAsJsonObject().get("access_token");
     			if(token != null && !token.isJsonNull()) {
     				accessToken = token.getAsString();
     			}
     		}
     		System.out.println("Access Token: " + accessToken);
     	}
     
     	/**
     	 * Fetches access token from given token end point
     	 * @param tokenEndPoint
     	 * @param apiKey
     	 * @param apiSecret
     	 * @return
     	 * @throws HttpException
     	 * @throws IOException
     	 */
     	public static String invokeTokenRequest(final String tokenEndPoint,
     			final String apiKey, final String apiSecret)
     			throws HttpException, IOException {
     		CloseableHttpClient httpclient = HttpClients.custom().build();
     		try {
     			List parametersBody = new ArrayList();
     			parametersBody.add(new BasicNameValuePair("grant_type", "client_credentials"));
     			parametersBody.add(new BasicNameValuePair("client_id", apiKey));
     			parametersBody.add(new BasicNameValuePair("client_secret", apiSecret));
     
     			HttpPost httpPost = new HttpPost(tokenEndPoint);
     			httpPost.setHeader(HttpHeaders.ACCEPT, ContentType.APPLICATION_JSON.toString());
     			httpPost.setHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_FORM_URLENCODED.toString());
     			httpPost.setEntity(new UrlEncodedFormEntity(parametersBody, StandardCharsets.UTF_8.toString()));
     
     			System.out.println("n" + httpPost.getRequestLine());
     			CloseableHttpResponse response = httpclient.execute(httpPost);
     			try {
     				System.out.println("Response " + response.getStatusLine());
     				String responseBody = null;
     				if(response.getEntity() != null) { 
     					responseBody = EntityUtils.toString(response.getEntity());
     				}
     				return responseBody;
     			} finally {
     				response.close();
     			}
     		} finally {
     			httpclient.close();
     		}
     	}
     }
     }

4. Capture OAuth authorization token from response

Note:

• Validity period of the access token is 2 hours.

• Repeat above instructions if the token expires.

Appendix – Generating API Requests

Example: Get inventory of managed resources within a client

Below are the sample codes to make an API request to get the inventory details of resources within a client.

1. Get list of Devices.

   • Curl

     curl -k -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X GET https://<api-url>/api/v2/tenants/client_622733/devices/minimal

2. Search device details by name.

   • Curl

     curl -k -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X GET https://<api-url>/api/v2/tenants/client_622733/devices/search?queryString=hostName:prod-Test-01

3. Search devices by UUID.

   • Curl

     curl -k -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X GET https://<api-url>/api/v2/tenants/client_622733/devices/search?queryString=resourceUUID:60c6f02e-5080-46a7-856b-f1f2a1997603

   • Python

     import urllib
     import urllib2
     import json, sys
     import time
     
     API_SERVER = "api.opsramp.com"
     CLIENT_ID  = "CLIENT_ID"
     API_KEY    = "API_KEY"
     API_SECRET = "API_SECRET"
     
     
     ''' Python HTTP client to make GET/POST requests '''
     def httpRequest(url, data=None, headers={}, method='GET',user=None, passwd=None):
         try: 
             http_headers = {
                 'Content-Type' : 'application/x-www-form-urlencoded',
                 'Accept'       : 'text/html, */*',
             }
             http_headers.update(headers)
             req = urllib2.Request(url, data, http_headers)
             req.get_method = lambda: method
             if user and passwd:
                 passReq = urllib2.HTTPPasswordMgrWithDefaultRealm()
                 passReq.add_password(None, url, user, passwd)
                 authhandler = urllib2.HTTPBasicAuthHandler(passReq)
                 opener = urllib2.build_opener(authhandler)
                 urllib2.install_opener(opener)
     
             request = urllib2.urlopen(req)
             return request.read()
         except urllib2.HTTPError, emsg:
             _msg = emsg.read()
             print emsg.getcode()
             if emsg.getcode() == 500:
                 print _msg
                 return _msg
             else:
                 print emsg.read()
                 raise Exception(emsg.reason)
             raise Exception('httpRequest: HTTPError - ' + str(emsg))
         except urllib2.URLError, emsg:
             raise Exception('httpRequest: URLError - ' + str(emsg))
         except Exception, emsg:
             raise Exception('httpRequest: Exception - ' + str(emsg))
     
     
     ''' Get resource/device information from OpsRamp '''
     def get_resources(ACCESS_TOKEN, query_string="", pageSize=500, pageNo=None):
         headers = {
             "Authorization" : "Bearer " + ACCESS_TOKEN,
             "Content-Type"  : "application/json"
         }
         device_search_url = "https://%s/api/v2/tenants/%s/devices/search?pageSize=%s&queryString=%s" 
                               % (API_SERVER, CLIENT_ID, pageSize, query_string)
         if pageNo:
             device_search_url += "&pageNo=" + str(pageNo)
         try:
             response = json.loads(httpRequest(device_search_url, None, headers))
             print "t" + device_search_url
             ''' Capture full devices information using response'''
             ''' print "t" + json.dumps(response)'''
             return response
         except Exception, emsg:
             print emsg
             print 'Resource does not exist in OPSRAMP, Please create new Resource'
             sys.exit(2)
     
     
     def get_devices_data(ACCESS_TOKEN, pageSize=500, query_string=""):
         devices = {}
             
         def get_device_data(rsrcInfo):
             for resource in rsrcInfo['results']:
                 devices[resource['id']] = resource['generalInfo']['hostName']
     
             if rsrcInfo['nextPage']:
                 rsrcs = get_resources(ACCESS_TOKEN, query_string, pageSize, rsrcInfo['pageNo'] + 1)
                 get_device_data(rsrcs)
                 
         resources = get_resources(ACCESS_TOKEN, query_string, pageSize)
         get_device_data(resources)
         return devices
     
     
     ''' Get OpsRamp access token using api key/secret for further communication '''
     def get_access_token():
         url = "https://%s/auth/oauth/token" % (API_SERVER)
     
         data = urllib.urlencode({
             "client_id"     : API_KEY,
             "client_secret" : API_SECRET,
             "grant_type"    : "client_credentials"
         })
     
         headers = {"Content-Type": "application/x-www-form-urlencoded", "Accept" : "application/json"}
         try:
             result = json.loads(httpRequest(url, data, headers, 'POST'))
             print "ntAccessToken: " + result['access_token'] + "n";
             return result['access_token']
         except Exception as emsg:
             raise Exception("Error while getting access token - " + str(emsg))
     
     
     ''' Execution starts here'''
     if __name__ == '__main__':
         try:
             
             ACCESS_TOKEN = str(get_access_token())
     
             pageSize=500
             query_string = ""
             
             devices = get_devices_data(ACCESS_TOKEN, pageSize, query_string)
             
             ''' All Device ids & names will be available in devices dictionary'''
             print json.dumps(devices)
         except Exception as e:
             print ("Failed: {0}".format(e))
             
         sys.exit(0)

   • Java

     package com.opsramp.examples.rest;
     
     import java.io.IOException;
     import java.util.Date;
     
     import org.apache.http.HttpException;
     import org.apache.http.HttpHeaders;
     import org.apache.http.client.methods.CloseableHttpResponse;
     import org.apache.http.client.methods.HttpGet;
     import org.apache.http.entity.ContentType;
     import org.apache.http.impl.client.CloseableHttpClient;
     import org.apache.http.impl.client.HttpClients;
     import org.apache.http.util.EntityUtils;
     
     /**
      * Sample program to fetch devices within a client
      */
     public class GetDevices {
     	
     	/**
     	 * Main program which invokes get devices request
     	 * @param args
     	 * @throws HttpException
     	 * @throws IOException
     	 */
     	public static void main(String[] args) throws HttpException, IOException {
     		//Replace the end point and access token accordingly
     		String ACCESS_TOKEN = "a0f46d75-534d-4180-b4ec-65a23eb1ae39";
     		
     		//Fetching devices minimal list
     		String ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/devices/minimal";
     		String response = invokeGetRequest(ACCESS_TOKEN, ENDPOINT, 0);
     		System.out.println(response);
     		
     		//Performing device search using host name
     		ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/devices/search"
     						+ "?queryString=hostName:HYDLPT323";
     		response = invokeGetRequest(ACCESS_TOKEN, ENDPOINT, 0);
     		System.out.println(response);
     		
     		//Performing device search using unique id
     		ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/devices/search"
     						+ "?queryString=resourceUUID:5486c82c-d5fc-4e40-b238-a4f00cb387da";
     		response = invokeGetRequest(ACCESS_TOKEN, ENDPOINT, 0);
     		System.out.println(response);
     	}
     	
     	/**
     	 * Fetches data from given end point
     	 * @param accessToken
     	 * @param endPoint
     	 * @return
     	 * @throws HttpException
     	 * @throws IOException
     	 */
     	public static String invokeGetRequest(final String accessToken, final String endPoint, final int currentRetryCount)
     			throws HttpException, IOException {
     		CloseableHttpClient httpclient = HttpClients.custom().build();
     		try {
     			HttpGet httpget = new HttpGet(endPoint);
     			httpget.setHeader(HttpHeaders.ACCEPT, ContentType.APPLICATION_JSON.toString());
     			httpget.setHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_JSON.toString());
     			httpget.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
     			
     			System.out.println("n" + httpget.getRequestLine());
     			CloseableHttpResponse response = httpclient.execute(httpget);
     			try {
     				System.out.println("Response " + response.getStatusLine());
     				String responseBody = null;
     				if(response.getEntity() != null) { 
     					responseBody = EntityUtils.toString(response.getEntity());
     					if(response.getStatusLine().getStatusCode() == 429) {
     						if(currentRetryCount > 3) {
     							System.out.println("Retry Max-Limit(3) reached; Dropping API: " + endPoint);
     						}
     						long resetTimeInSeconds = Long.valueOf(response.getFirstHeader("X-RateLimit-Reset").getValue());
     						long retryInSec = resetTimeInSeconds - (new Date().getTime()/1000);
     						System.out.println("tNext retry in: " + retryInSec + "s" + " | " + endPoint);
     						try {
     							Thread.sleep(retryInSec*1000);
     						} catch(Exception ex) {}
     						invokeGetRequest(accessToken, endPoint, currentRetryCount+1);
     					}
     				}
     				return responseBody;
     			} finally {
     				response.close();
     			}
     		} finally {
     			httpclient.close();
     		}
     	}
     }

Example: Get time series metric data for a managed resource

Below are the sample codes to generate an API request to get metric data for a managed resource.

1. Get resource ID and resource type using Search Devices API.

   • Curl

     curl -k -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X GET "https://<api-url>/api/v2/tenants/client_622733/devices/search?queryString=hostName:prod-Test-01"

2. Capture resource ID and resource type from the response.

3. Get metric name from the list of available metrics on a device.

   • Curl

     curl -k -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X GET "https://<api-url>/api/v2/metric/tenants/client_622733/rtypes/DEVICE/resources/i-4cf5c094/metrics"

4. Capture metric from response Get the time series response for the resource ID, resource type and metric (startTime and endTime are UNIX timestamps).

   • Curl

     curl -k -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X GET "https://<api-url>/api/v2/metric/search?tenant=client_622733&rtype=DEVICE&resource=i-4cf5c094&metric=system.cpu.utilization&startTime=1444973469&endTime=1445002269"

Sample metric and start/end times are metric=system.cpu.utilization&startTime=1444973469&endTime=1463772116049

Note:

1. Start/end dates from the curl from Linux

   • date +%s #Current time

   • date -d “1 hour ago” +%s #1 Hour ago

   • date -d “1 day ago” +%s #1 Day ago

   • date -d “1 month ago” +%s #1 Month ago

2. Start/end dates from the curl from OS X

   • date +%s #Current time

   • date -v-1H +%s #1 Hour ago

   • date -v-1d +%s #1 Day ago

   • date -v-1m +%s #1 Month ago

• • Python

    import urllib
    import urllib2
    import json, sys
    import time
    
    API_SERVER = "api.opsramp.com"
    CLIENT_ID  = "CLIENT_ID"
    API_KEY    = "API_KEY"
    API_SECRET = "API_SECRET"
    
    
    ''' Python HTTP client to generate GET/POST requests '''
    def httpRequest(url, data=None, headers={}, repeat_count=None, method='GET',user=None, passwd=None):
        try:
            http_headers = {
                'Content-Type' : 'application/x-www-form-urlencoded',
                'Accept'       : 'text/html, */*',
            }
            http_headers.update(headers)
            req = urllib2.Request(url, data, http_headers)
            req.get_method = lambda: method
            if user and passwd:
                passReq = urllib2.HTTPPasswordMgrWithDefaultRealm()
                passReq.add_password(None, url, user, passwd)
                authhandler = urllib2.HTTPBasicAuthHandler(passReq)
                opener = urllib2.build_opener(authhandler)
                urllib2.install_opener(opener)
    
            request = urllib2.urlopen(req)
            return request.read()
        except urllib2.HTTPError, emsg:
            _msg = emsg.read()
            print emsg.getcode()
            if emsg.getcode() == 429:
                time.sleep(60)
                if repeat_count != None and repeat_count < 3:
                    httpRequest(url, data, headers, repeat_count+1, method)
                print _msg
                return _msg
            elif emsg.getcode() == 500:
                print _msg
                return _msg
            else:
                print emsg.read()
                raise Exception(emsg.reason)
            raise Exception('httpRequest: HTTPError - ' + str(emsg))
        except urllib2.URLError, emsg:
            raise Exception('httpRequest: URLError - ' + str(emsg))
        except Exception, emsg:
            raise Exception('httpRequest: Exception - ' + str(emsg))
    
    
    ''' Get metrics '''
    def get_available_metrics(rsrc_id, rsrc_type):
        try:
            headers = {
                "Authorization" : "Bearer " + ACCESS_TOKEN,
                "Content-Type"  : "application/json",
                "Accept"        : "application/json"
            }
            available_metrics_url = "https://{0}/api/v2/metric/tenants/{1}/rtypes/{2}/resources/{3}/metrics" 
            % (API_SERVER, CLIENT_ID, rsrc_type, rsrc_id)
    
            return httpRequest(available_metrics_url, None, headers, 0, 'GET')
        except Exception as emsg:
            print 'Failed to get metric data %s' % (emsg)
            
    
    ''' Time Series metrics data'''
    def get_timeseries_metrics_data(rsrc_id, rsrc_type,metric_name,start_time,end_time):
        try:
            headers = {
                "Authorization" : "Bearer " + ACCESS_TOKEN,
                "Content-Type"  : "application/json",
                "Accept"        : "application/json"
            }
            
            timeseries_metrics_url = "https://{0}/api/v2/metric/search?tenant={1}&rtype={2}&resource={3}&metric={4}&startTime={5}&endTime={6}" 
             % (API_SERVER, CLIENT_ID, rsrc_type, rsrc_id, metric_name,start_time,end_time)
    
            return httpRequest(timeseries_metrics_url, None, headers, 0, 'GET')
        except Exception as emsg:
            print 'Failed to post metric data %s' % (emsg)
    
    
    ''' Get OpsRamp access token using api key/secret for further communication '''
    def get_access_token():
        url = "https://%s/auth/oauth/token" % (API_SERVER)
    
        data = urllib.urlencode({
            "client_id"     : API_KEY,
            "client_secret" : API_SECRET,
            "grant_type"    : "client_credentials"
        })
    
        headers = {"Content-Type": "application/x-www-form-urlencoded", "Accept" : "application/json"}
        try:
            result = json.loads(httpRequest(url, data, headers, None, 'POST'))
            return result['access_token']
        except Exception as emsg:
            raise Exception("Error while getting access token - " + str(emsg))
    
    
    if __name__ == '__main__':
        try:
            global ACCESS_TOKEN
            ACCESS_TOKEN = str(get_access_token())
            
            RESOURCE_TYPE = "DEVICE"
            RESOURCE_ID = "702c19c4-1991-4e99-8c5f-4104c061fe25"
            
            available_metrics = get_available_metrics(RESOURCE_ID, RESOURCE_TYPE) 
    
            ''' Fetching time series metric data for the resource '''
    
            METRIC_NAME = 'vistara.agent.status'
            
            ''' start time and end time in epoch time '''
            start_time = "1444973469"
            end_time = "1467980181"
            timeseries_data = get_timeseries_metrics_data(RESOURCE_ID, RESOURCE_TYPE, METRIC_NAME,start_time,end_time)
        
        except Exception as e:
            print ("Failed: {0}".format(e))
            
        sys.exit(0)

    • Java

      package com.opsramp.examples.rest;
      
      import java.io.IOException;
      import java.net.URLEncoder;
      import java.nio.charset.StandardCharsets;
      import java.util.Date;
      
      import org.apache.http.HttpException;
      import org.apache.http.HttpHeaders;
      import org.apache.http.client.methods.CloseableHttpResponse;
      import org.apache.http.client.methods.HttpGet;
      import org.apache.http.entity.ContentType;
      import org.apache.http.impl.client.CloseableHttpClient;
      import org.apache.http.impl.client.HttpClients;
      import org.apache.http.util.EntityUtils;
      
      import com.google.gson.JsonElement;
      import com.google.gson.JsonParser;
      
      /**
       * Sample program to get time series metric data of a resource
       */
      public class GetTimeSeriesMetricData {
      	
      	/**
      	 * Main program which invokes time series metric data request
      	 * @param args
      	 * @throws HttpException
      	 * @throws IOException
      	 */
      	public static void main(String[] args) throws HttpException, IOException {
      		//Replace the end point and access token accordingly
      		String ACCESS_TOKEN = "a0f46d75-534d-4180-b4ec-65a23eb1ae39";
      		
      		//Performing device search using host name
      		String ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/devices/search"
      					+ "?queryString=" + URLEncoder.encode("hostName:HYDLPT220", StandardCharsets.UTF_8.toString());
      		URLEncoder.encode(ENDPOINT, StandardCharsets.UTF_8.toString());
      		String response = invokeGetRequest(ACCESS_TOKEN, ENDPOINT, 0);
      		if(response == null || response.isEmpty()) {
      			return;
      		}
      		System.out.println(response);
      		
      		//Capturing resource id and type from response
      		JsonElement json = new JsonParser().parse(response);
      		JsonElement count = json.getAsJsonObject().get("totalResults");
      		if(count == null || count.isJsonNull()) {
      			return;
      		}
      		if(count.getAsInt() == 0) {
      			return;
      		}
      		JsonElement resourceJson = json.getAsJsonObject().get("results")
      										.getAsJsonArray().get(0);
      		String resourceUID = null, resourceType = null;
      		if(resourceJson.getAsJsonObject().get("id") != null) {
      			resourceUID = resourceJson.getAsJsonObject().get("id").getAsString();
      		}
      		if(resourceJson.getAsJsonObject().get("type") != null) {
      			resourceType = resourceJson.getAsJsonObject().get("type").getAsString();
      		}
      		System.out.println("Total Results: " + count.getAsInt());
      		System.out.println("Resource Id: " + resourceUID);
      		System.out.println("Resource Type: " + resourceType);
      		
      		if(resourceUID == null || resourceUID.isEmpty() 
      				|| resourceType == null || resourceType.isEmpty()) {
      			return;
      		}
      
      		//Fetching available metrics list of the resource
      		ENDPOINT = "https://<api-url>/api/v2/metric/tenants/client_99999"
      						+ "/rtypes/" + resourceType+ "/resources/" + resourceUID+ "/metrics";
      		response = invokeGetRequest(ACCESS_TOKEN, ENDPOINT, 0);
      		if(response == null || response.isEmpty()) {
      			return;
      		}
      		System.out.println(response);
      		
      		//Capturing metric name from response
      		json = new JsonParser().parse(response);
      		if(!json.isJsonArray() || json.getAsJsonArray().size() == 0) {
      			return;
      		}
      		
      		JsonElement metricJson = json.getAsJsonArray().get(0);
      		
      		String metricName = null;
      		if(metricJson.getAsJsonObject().get("metricName") != null) {
      			metricName = metricJson.getAsJsonObject().get("metricName").getAsString();
      		}
      		if(metricName == null || metricName.isEmpty()) {
      			return;
      		}
      		System.out.println("Metric Name: " + metricName);
      		
      		//Fetching time series metric data for the resource
      		ENDPOINT = "https://<api-url>/api/v2/metric/search?tenant=client_99999"
      						+ "&rtype=" + resourceType + "&resource=" + resourceUID + 
      						"&metric=" + metricName + "&startTime=1444973469&endTime=1467980181";
      		response = invokeGetRequest(ACCESS_TOKEN, ENDPOINT, 0);
      		System.out.println(response);
      	}
      	
      	/**
      	 * Fetches data from given end point
      	 * @param accessToken
      	 * @param endPoint
      	 * @return
      	 * @throws HttpException
      	 * @throws IOException
      	 */
      	public static String invokeGetRequest(final String accessToken, final String endPoint, final int currentRetryCount)
      			throws HttpException, IOException {
      		CloseableHttpClient httpclient = HttpClients.custom().build();
      		try {
      			HttpGet httpget = new HttpGet(endPoint);
      			httpget.setHeader(HttpHeaders.ACCEPT, ContentType.APPLICATION_JSON.toString());
      			httpget.setHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_JSON.toString());
      			httpget.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
      			
      			System.out.println("n" + httpget.getRequestLine());
      			CloseableHttpResponse response = httpclient.execute(httpget);
      			try {
      				System.out.println("Response " + response.getStatusLine());
      				String responseBody = null;
      				if(response.getEntity() != null) { 
      					responseBody = EntityUtils.toString(response.getEntity());
      					if(response.getStatusLine().getStatusCode() == 429) {
      						if(currentRetryCount > 3) {
      							System.out.println("Retry Max-Limit(3) reached; Dropping API: " + endPoint);
      						}
      						long resetTimeInSeconds = Long.valueOf(response.getFirstHeader("X-RateLimit-Reset").getValue());
      						long retryInSec = resetTimeInSeconds - (new Date().getTime()/1000);
      						System.out.println("tNext retry in: " + retryInSec + "s" + " | " + endPoint);
      						try {
      							Thread.sleep(retryInSec*1000);
      						} catch(Exception ex) {}
      						invokeGetRequest(accessToken, endPoint, currentRetryCount+1);
      					}
      				}
      				return responseBody;
      			} finally {
      				response.close();
      			}
      		} finally {
      			httpclient.close();
      		}
      	}
      }

Example: Post a metric against a resource

Below are the sample codes to generate an API request to post a metric on a resource.

• Curl

  curl -k https://<api-url>/api/v2/metric/tenants/client_622733/rtypes/DEVICE/resources/i-4cf5c094/metrics -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept: application/json" -d '[{"metricName" : "system.cpu.utilization","instanceName" : "system.cpu.utilization","instanceVal" : "13.50","ts" : "1448274610"}]' -X POST

• Python

  import urllib
  import urllib2
  import json, sys
  import time
  
  API_SERVER = "API_SERVER"
  CLIENT_ID  = "CLIENT_ID"
  API_KEY    = "API_KEY"
  API_SECRET = "API_SECRET"
  
  
  ''' Python HTTP client to generate GET/POST requests '''
  def httpRequest(url, data=None, headers={}, method='GET',user=None, passwd=None):
      try: 
          http_headers = {
              'Content-Type' : 'application/x-www-form-urlencoded',
              'Accept'       : 'text/html, */*',
          }
          http_headers.update(headers)
          req = urllib2.Request(url, data, http_headers)
          req.get_method = lambda: method
          if user and passwd:
              passReq = urllib2.HTTPPasswordMgrWithDefaultRealm()
              passReq.add_password(None, url, user, passwd)
              authhandler = urllib2.HTTPBasicAuthHandler(passReq)
              opener = urllib2.build_opener(authhandler)
              urllib2.install_opener(opener)
  
          request = urllib2.urlopen(req)
          return request.read()
      except urllib2.HTTPError, emsg:
          _msg = emsg.read()
          print emsg.getcode()
          if emsg.getcode() == 500:
              print _msg
              return _msg
          else:
              print emsg.read()
              raise Exception(emsg.reason)
          raise Exception('httpRequest: HTTPError - ' + str(emsg))
      except urllib2.URLError, emsg:
          raise Exception('httpRequest: URLError - ' + str(emsg))
      except Exception, emsg:
          raise Exception('httpRequest: Exception - ' + str(emsg))
  
  
  ''' Post metrics '''
  def post_metrics(rsrc_id, metric_data):
      try:
          headers = {
              "Authorization" : "Bearer " + config.access_token,
              "Content-Type"  : "application/json",
              "Accept"        : "application/json"
          }
          post_metrics_url = "https://%s/api/v2/metric/tenants/%s/rtypes/DEVICE/resources/%s/metrics" % (API_SERVER, CLIENT_ID, rsrc_id)
          data = str(json.dumps(metric_data))
  
          httpRequest(post_metrics_url, data, headers, 'POST')
      except Exception as emsg:
          print 'Failed to post metric data %s' % (emsg)
  
  
  ''' Get OpsRamp access token using api key/secret for further communication '''
  def get_access_token():
      url = "https://%s/auth/oauth/token" % (API_SERVER)
  
      data = urllib.urlencode({
          "client_id"     : API_KEY,
          "client_secret" : API_SECRET,
          "grant_type"    : "client_credentials"
      })
  
      headers = {"Content-Type": "application/x-www-form-urlencoded", "Accept" : "application/json"}
      try:
          result = json.loads(httpRequest(url, data, headers, 'POST'))
          return result['access_token']
      except Exception as emsg:
          raise Exception("Error while getting access token - " + str(emsg))
  
  
  if __name__ == '__main__':
      try:
          global ACCESS_TOKEN
          ACCESS_TOKEN = str(get_access_token())
          
          RESOURCE_ID = "702c19c4-1991-4e99-8c5f-4104c061fe25"
          
          metric_data = [{
              "metricName"   : "system.ping.rta",
              "instanceVal"  : "16.50",
              "instanceName" : "rta",
              "ts"           : "1467983770"
          }]
  
          post_metrics(RESOURCE_ID, metric_data)
      
      except Exception as e:
          print ("Failed: {0}".format(e))
          
      sys.exit(0)

• Java

  package com.opsramp.examples.rest;
  
  import java.io.IOException;
  import java.nio.charset.StandardCharsets;
  import java.util.Date;
  
  import org.apache.http.HttpException;
  import org.apache.http.HttpHeaders;
  import org.apache.http.client.methods.CloseableHttpResponse;
  import org.apache.http.client.methods.HttpPost;
  import org.apache.http.entity.ByteArrayEntity;
  import org.apache.http.entity.ContentType;
  import org.apache.http.impl.client.CloseableHttpClient;
  import org.apache.http.impl.client.HttpClients;
  import org.apache.http.util.EntityUtils;
  
  /**
   * Sample program to post metric against a resource
   */
  public class PostMetric {
  	
  	/**
  	 * Main program which posts a metric against a resource
  	 * @param args
  	 * @throws HttpException
  	 * @throws IOException
  	 */
  	public static void main(String[] args) throws HttpException, IOException {
  		//Replace the end point and access token accordingly
  		String ACCESS_TOKEN = "a0f46d75-534d-4180-b4ec-65a23eb1ae39";
  		
  		//Posting a metric
  		String ENDPOINT = "https://<api-url>/api/v2/metric/tenants/client_99999"
  								+ "/rtypes/DEVICE/resources/702c19c4-1991-4e99-8c5f-4104c061fe25/metrics";
  		String PAYLOAD = "[{"metricName" : "system.ping.rta","instanceName": "rta","
  								+ ""instanceVal" : "16.50","ts" : "1467983770"}]";
  		String response = invokePostRequest(ACCESS_TOKEN, ENDPOINT, PAYLOAD, 0);
  		System.out.println(response);
  	}
  	
  	/**
  	 * Posts data to given end point
  	 * @param accessToken
  	 * @param endPoint
  	 * @param payload
  	 * @return
  	 * @throws HttpException
  	 * @throws IOException
  	 */
  	public static String invokePostRequest(final String accessToken, final String endPoint,
  			final String payload, final int currentRetryCount) throws HttpException, IOException {
  		CloseableHttpClient httpclient = HttpClients.custom().build();
  		try {
  			HttpPost httpPost = new HttpPost(endPoint);
  			httpPost.setHeader(HttpHeaders.ACCEPT, ContentType.APPLICATION_JSON.toString());
  			httpPost.setHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_JSON.toString());
  			httpPost.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
  			httpPost.setEntity(new ByteArrayEntity(payload.getBytes(StandardCharsets.UTF_8.toString())));
  
  			System.out.println("n" + httpPost.getRequestLine());
  			CloseableHttpResponse response = httpclient.execute(httpPost);
  			try {
  				System.out.println("Response " + response.getStatusLine());
  				String responseBody = null;
  				if(response.getEntity() != null) { 
  					responseBody = EntityUtils.toString(response.getEntity());
  					if(response.getStatusLine().getStatusCode() == 429) {
  						if(currentRetryCount > 3) {
  							System.out.println("Retry Max-Limit(3) reached; Dropping API: " + endPoint);
  						}
  						long resetTimeInSeconds = Long.valueOf(response.getFirstHeader("X-RateLimit-Reset").getValue());
  						long retryInSec = resetTimeInSeconds - (new Date().getTime()/1000);
  						System.out.println("tNext retry in: " + retryInSec + "s" + " | " + endPoint);
  						try {
  							Thread.sleep(retryInSec*1000);
  						} catch(Exception ex) {}
  						invokePostRequest(accessToken, endPoint, payload, currentRetryCount+1);
  					}
  				}
  				return responseBody;
  			} finally {
  				response.close();
  			}
  		} finally {
  			httpclient.close();
  		}
  	}
  }

Example: Get open alerts

Below are the sample codes to generate an API request to get the list of open alerts.

• Curl

  curl -k -H “Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570” -H “Content-Type: application/json” -H “Accept:application/json” -X GET “https://<partner_name>.api.ospramp.com/api/v2/tenants/client_622733/alerts/search?queryString=actions:OPEN”

• Python

  import urllib
  import urllib2
  import json, sys
  import time
  
  API_SERVER = "API_SERVER"
  CLIENT_ID  = "CLIENT_ID"
  API_KEY    = "API_KEY"
  API_SECRET = "API_SECRET"
  
  
  ''' Python HTTP client to generate GET/POST requests '''
  def httpRequest(url, data=None, headers={}, method='GET',user=None, passwd=None):
      try: 
          http_headers = {
              'Content-Type' : 'application/x-www-form-urlencoded',
              'Accept'       : 'text/html, */*',
          }
          http_headers.update(headers)
          req = urllib2.Request(url, data, http_headers)
          req.get_method = lambda: method
          if user and passwd:
              passReq = urllib2.HTTPPasswordMgrWithDefaultRealm()
              passReq.add_password(None, url, user, passwd)
              authhandler = urllib2.HTTPBasicAuthHandler(passReq)
              opener = urllib2.build_opener(authhandler)
              urllib2.install_opener(opener)
  
          request = urllib2.urlopen(req)
          return request.read()
      except urllib2.HTTPError, emsg:
          _msg = emsg.read()
          print emsg.getcode()
          if emsg.getcode() == 500:
              print _msg
              return _msg
          else:
              print emsg.read()
              raise Exception(emsg.reason)
          raise Exception('httpRequest: HTTPError - ' + str(emsg))
      except urllib2.URLError, emsg:
          raise Exception('httpRequest: URLError - ' + str(emsg))
      except Exception, emsg:
          raise Exception('httpRequest: Exception - ' + str(emsg))
  
  
  ''' Get open alerts information from OpsRamp '''
  def get_open_alerts(ACCESS_TOKEN, query_string=""):
      headers = {
          "Authorization" : "Bearer " + ACCESS_TOKEN,
          "Content-Type"  : "application/json"
      }
      alerts_search_url = "https://%s/api/v2/tenants/%s/alerts/search?queryString=%s" % (API_SERVER, CLIENT_ID, query_string)
  
      try:
          response = json.loads(httpRequest(device_search_url, None, headers))
          return response
      except Exception, emsg:
          print emsg
          sys.exit(2)
  
  
  ''' Get OpsRamp access token using api key/secret for further communication '''
  def get_access_token():
      url = "https://%s/auth/oauth/token" % (API_SERVER)
  
      data = urllib.urlencode({
          "client_id"     : API_KEY,
          "client_secret" : API_SECRET,
          "grant_type"    : "client_credentials"
      })
  
      headers = {"Content-Type": "application/x-www-form-urlencoded", "Accept" : "application/json"}
      try:
          result = json.loads(httpRequest(url, data, headers, 'POST'))
          return result['access_token']
      except Exception as emsg:
          raise Exception("Error while getting access token - " + str(emsg))
  
  
  if __name__ == '__main__':
      try:
          
          ACCESS_TOKEN = str(get_access_token())
  
          ''' need to provide the query string based on requirement '''
          query_string = "actions:OPEN"
          open_alerts = get_open_alerts(ACCESS_TOKEN,query_string)
      
      except Exception as e:
          print ("Failed: {0}".format(e))
          
      sys.exit(0)

• Java

  package com.opsramp.examples.rest;
  
  import java.io.IOException;
  import java.util.Date;
  
  import org.apache.http.HttpException;
  import org.apache.http.HttpHeaders;
  import org.apache.http.client.methods.CloseableHttpResponse;
  import org.apache.http.client.methods.HttpGet;
  import org.apache.http.entity.ContentType;
  import org.apache.http.impl.client.CloseableHttpClient;
  import org.apache.http.impl.client.HttpClients;
  import org.apache.http.util.EntityUtils;
  
  /**
   * Sample program to fetch open alerts within a client
   */
  public class GetOpenAlerts {
  	
  	/**
  	 * Main program which invokes get open alerts request
  	 * @param args
  	 * @throws HttpException
  	 * @throws IOException
  	 */
  	public static void main(String[] args) throws HttpException, IOException {
  		//Replace the end point and access token accordingly
  		String ACCESS_TOKEN = "a0f46d75-534d-4180-b4ec-65a23eb1ae39";
  		
  		//Fetching open alerts
  		String ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/alerts/search"
  								+ "?queryString=actions:OPEN";
  		String response = invokeGetRequest(ACCESS_TOKEN, ENDPOINT, 0);
  		System.out.println(response);
  	}
  	
  	/**
  	 * Fetches data from given end point
  	 * @param accessToken
  	 * @param endPoint
  	 * @return
  	 * @throws HttpException
  	 * @throws IOException
  	 */
  	public static String invokeGetRequest(final String accessToken, final String endPoint, final int currentRetryCount)
  			throws HttpException, IOException {
  		CloseableHttpClient httpclient = HttpClients.custom().build();
  		try {
  			HttpGet httpget = new HttpGet(endPoint);
  			httpget.setHeader(HttpHeaders.ACCEPT, ContentType.APPLICATION_JSON.toString());
  			httpget.setHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_JSON.toString());
  			httpget.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
  			
  			System.out.println("n" + httpget.getRequestLine());
  			CloseableHttpResponse response = httpclient.execute(httpget);
  			try {
  				System.out.println("Response " + response.getStatusLine());
  				String responseBody = null;
  				if(response.getEntity() != null) { 
  					responseBody = EntityUtils.toString(response.getEntity());
  					if(response.getStatusLine().getStatusCode() == 429) {
  						if(currentRetryCount > 3) {
  							System.out.println("Retry Max-Limit(3) reached; Dropping API: " + endPoint);
  						}
  						long resetTimeInSeconds = Long.valueOf(response.getFirstHeader("X-RateLimit-Reset").getValue());
  						long retryInSec = resetTimeInSeconds - (new Date().getTime()/1000);
  						System.out.println("tNext retry in: " + retryInSec + "s" + " | " + endPoint);
  						try {
  							Thread.sleep(retryInSec*1000);
  						} catch(Exception ex) {}
  						invokeGetRequest(accessToken, endPoint, currentRetryCount+1);
  					}
  				}
  				return responseBody;
  			} finally {
  				response.close();
  			}
  		} finally {
  			httpclient.close();
  		}
  	}
  }

Example: Post an alert against a resource

Below are the sample codes to generate an API request to post alerts on a resource.

• Curl

  curl -k https://<api-url>/api/v2/tenants/client_622733/alert -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept: application/json" -d '{"serviceName": "CPU","device":{"hostName":"Think-pad","resourceUUID":"DEV0000011767","providerUUID":"11767","systemUUID":"11767","macAddress":"2E:8B:EB:32:7A:F9","ipAddress":"172.2.229.109"},"subject":"Test API Alert for car", "alertTime":"2014-11-05 11:26:00","currentState":"CRITICAL", "app":"OPSRAMP","alertType":"Maintenance","component": "C","description":"api calls","monitorName":"test"}'

• Python

  import urllib
  import urllib2
  import json, sys
  import time
  
  API_SERVER = "API_SERVER"
  CLIENT_ID  = "CLIENT_ID"
  API_KEY    = "API_KEY"
  API_SECRET = "API_SECRET"
  
  
  ''' Python HTTP client to generate GET/POST requests '''
  def httpRequest(url, data=None, headers={}, method='GET',user=None, passwd=None):
      try: 
          http_headers = {
              'Content-Type' : 'application/x-www-form-urlencoded',
              'Accept'       : 'text/html, */*',
          }
          http_headers.update(headers)
          req = urllib2.Request(url, data, http_headers)
          req.get_method = lambda: method
          if user and passwd:
              passReq = urllib2.HTTPPasswordMgrWithDefaultRealm()
              passReq.add_password(None, url, user, passwd)
              authhandler = urllib2.HTTPBasicAuthHandler(passReq)
              opener = urllib2.build_opener(authhandler)
              urllib2.install_opener(opener)
  
          request = urllib2.urlopen(req)
          return request.read()
      except urllib2.HTTPError, emsg:
          _msg = emsg.read()
          print emsg.getcode()
          if emsg.getcode() == 500:
              print _msg
              return _msg
          else:
              print emsg.read()
              raise Exception(emsg.reason)
          raise Exception('httpRequest: HTTPError - ' + str(emsg))
      except urllib2.URLError, emsg:
          raise Exception('httpRequest: URLError - ' + str(emsg))
      except Exception, emsg:
          raise Exception('httpRequest: Exception - ' + str(emsg))
  
  
  ''' Post alert using REST API '''
  def post_alert(resource_name, resource_ip, mname, mvalue, poll_time, component=""):
      alert_payload = {
        "serviceName": mname,
        "device": {
          "hostName": resource_name,
          "ipAddress": resource_ip
        },
        "subject": "Critical. %s=%s" % (mname, mvalue),
        "description": "Critical. %s=%s" % (mname, mvalue),
        "alertTime": time.strftime("%F %T", time.gmtime(poll_time)),
        "currentState": "Critical",
        "alertType": "Monitoring",
        "app": "OPSRAMP",
        "component": "%s-%s" % (mname, component)
      }
      headers = {
          "Authorization" : "Bearer " + ACCESS_TOKEN
      }
      alert_url = "https://%s/api/v2/tenants/%s/alert" % (API_SERVER, CLIENT_ID)
      
      data = str(json.dumps(alert_payload))
  
      httpRequest(alert_url, data, headers, 'POST')
  
  
  ''' Get OpsRamp access token using api key/secret for further communication '''
  def get_access_token():
      url = "https://%s/auth/oauth/token" % (API_SERVER)
  
      data = urllib.urlencode({
          "client_id"     : API_KEY,
          "client_secret" : API_SECRET,
          "grant_type"    : "client_credentials"
      })
  
      headers = {"Content-Type": "application/x-www-form-urlencoded", "Accept" : "application/json"}
      try:
          result = json.loads(httpRequest(url, data, headers, 'POST'))
          return result['access_token']
      except Exception as emsg:
          raise Exception("Error while getting access token - " + str(emsg))
  
  
  if __name__ == '__main__':
      try:
          global ACCESS_TOKEN
          ACCESS_TOKEN = str(get_access_token())
          
          resource_name = "BVRMLPT057"
          resource_ip = "172.28.102.50"
          mname = "CPU"
          mvalue = "90"
          poll_time = "2014-11-05 11:26:00"
  
          post_alert(resource_name, resource_ip, mname, mvalue, poll_time)
      
      except Exception as e:
          print ("Failed: {0}".format(e))
          
      sys.exit(0)

• Java

  package com.opsramp.examples.rest;
  
  import java.io.IOException;
  import java.nio.charset.StandardCharsets;
  import java.util.Date;
  
  import org.apache.http.HttpException;
  import org.apache.http.HttpHeaders;
  import org.apache.http.client.methods.CloseableHttpResponse;
  import org.apache.http.client.methods.HttpPost;
  import org.apache.http.entity.ByteArrayEntity;
  import org.apache.http.entity.ContentType;
  import org.apache.http.impl.client.CloseableHttpClient;
  import org.apache.http.impl.client.HttpClients;
  import org.apache.http.util.EntityUtils;
  
  /**
   * Sample program to post an alert against a resource
   */
  public class PostAlert {
  	
  	/**
  	 * Main program which posts an alert against a resource
  	 * @param args
  	 * @throws HttpException
  	 * @throws IOException
  	 */
  	public static void main(String[] args) throws HttpException, IOException {
  		//Replace the end point and access token accordingly
  		String ACCESS_TOKEN = "a0f46d75-534d-4180-b4ec-65a23eb1ae39";
  		
  		//Posting an alert
  		String ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/alert";
  		String PAYLOAD = "{"serviceName": "CPU","device":{"hostName":"HYDLPT220","
  				+ ""resourceUUID":"702c19c4-1991-4e99-8c5f-4104c061fe25","systemUUID":"11767","
  				+ ""macAddress":"2E:8B:EB:32:7A:F9","ipAddress":"172.2.229.109"},"subject":"Test API Alert","
  				+ ""alertTime":"2014-11-05 11:26:00","currentState":"CRITICAL", "app":"OPSRAMP","
  				+ ""alertType":"Maintenance","component": "C","description":"Test Alert from API Call","
  				+ ""monitorName":"TEST"}";
  		String response = invokePostRequest(ACCESS_TOKEN, ENDPOINT, PAYLOAD, 0);
  		System.out.println(response);
  	}
  	
  	/**
  	 * Posts data to given end point
  	 * @param accessToken
  	 * @param endPoint
  	 * @param payload
  	 * @return
  	 * @throws HttpException
  	 * @throws IOException
  	 */
  	public static String invokePostRequest(final String accessToken, final String endPoint,
  			final String payload, final int currentRetryCount) throws HttpException, IOException {
  		CloseableHttpClient httpclient = HttpClients.custom().build();
  		try {
  			HttpPost httpPost = new HttpPost(endPoint);
  			httpPost.setHeader(HttpHeaders.ACCEPT, ContentType.APPLICATION_JSON.toString());
  			httpPost.setHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_JSON.toString());
  			httpPost.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
  			httpPost.setEntity(new ByteArrayEntity(payload.getBytes(StandardCharsets.UTF_8.toString())));
  
  			System.out.println("n" + httpPost.getRequestLine());
  			CloseableHttpResponse response = httpclient.execute(httpPost);
  			try {
  				System.out.println("Response " + response.getStatusLine());
  				String responseBody = null;
  				if(response.getEntity() != null) { 
  					responseBody = EntityUtils.toString(response.getEntity());
  					if(response.getStatusLine().getStatusCode() == 429) {
  						if(currentRetryCount > 3) {
  							System.out.println("Retry Max-Limit(3) reached; Dropping API: " + endPoint);
  						}
  						long resetTimeInSeconds = Long.valueOf(response.getFirstHeader("X-RateLimit-Reset").getValue());
  						long retryInSec = resetTimeInSeconds - (new Date().getTime()/1000);
  						System.out.println("tNext retry in: " + retryInSec + "s" + " | " + endPoint);
  						try {
  							Thread.sleep(retryInSec*1000);
  						} catch(Exception ex) {}
  						invokePostRequest(accessToken, endPoint, payload, currentRetryCount+1);
  					}
  				}
  				return responseBody;
  			} finally {
  				response.close();
  			}
  		} finally {
  			httpclient.close();
  		}
  	}
  }

Example: Assign schedule maintenance to a device

Below are the sample codes to generate an API request to manage the schedule maintenance window.

1. Create a schedule maintenance window.

   • Curl

     curl -k -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X POST https://<api-url>/api/v2/tenants/client_622733/scheduleMaintenances -d

     {
     	"name": "Schedule-Maintenances-Name",
     	"description": "Schedule-Maintenances-DESC",
     	"dontRunRBA": "false",
     	"dontInstallPatch": "false",
     	"devices": [{
     		"hostName": "prod-Test-01"
     	}],
     	"schedule": {
     		"type": "One-Time",
     		"startTime": "2016-07-01T08:21:00+0000",
     		"endTime": "2016-07-01T08:45:00+0000",
     		"timezone": "America/Los_Angeles"
     	}
     }

2. Search for a scheduled maintenance window by name.

   • Curl

     curl -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X GET https://<api-url>/api/v2/tenants/client_603003/scheduleMaintenances/search?queryString=name:ondemand

3. Suspend a scheduled maintenance window.

   • Curl

     curl -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X POST https://<api-url>/api/v2/tenants/client_603003/scheduleMaintenances/346248/suspend

4. Resume a scheduled maintenance window.

   • Curl

     curl -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X POST https://<api-url>/api/v2/tenants/client_603003/scheduleMaintenances/346248/resume

5. Delete a scheduled maintenance window.

   • Curl

     curl -H "Authorization: Bearer be1eb787-9994-4de8-b060-4d1b201eb570" -H "Content-Type: application/json" -H "Accept:application/json" -X DELETE https://<api-url>/api/v2/tenants/client_603003/scheduleMaintenances/346248

Below are the sample codes of Python and Java to manage a schedule maintenance window.

• • Python

    import urllib
    import urllib2
    import json, sys
    import time
    
    API_SERVER = "api.opsramp.com"
    CLIENT_ID  = "CLIENT_ID"
    API_KEY    = "API_KEY"
    API_SECRET = "API_SECRET"
    
    
    ''' Python HTTP client to generate GET/POST requests '''
    def httpRequest(url, data=None, headers={}, repeat_count=None, method='GET',user=None, passwd=None):
        try:
            http_headers = {
                'Content-Type' : 'application/x-www-form-urlencoded',
                'Accept'       : 'text/html, */*',
            }
            http_headers.update(headers)
            req = urllib2.Request(url, data, http_headers)
            req.get_method = lambda: method
            if user and passwd:
                passReq = urllib2.HTTPPasswordMgrWithDefaultRealm()
                passReq.add_password(None, url, user, passwd)
                authhandler = urllib2.HTTPBasicAuthHandler(passReq)
                opener = urllib2.build_opener(authhandler)
                urllib2.install_opener(opener)
    
            request = urllib2.urlopen(req)
            return request.read()
        except urllib2.HTTPError, emsg:
            _msg = emsg.read()
            print emsg.getcode()
            if emsg.getcode() == 429:
                time.sleep(60)
                if repeat_count != None and repeat_count < 3:
                    httpRequest(url, data, headers, repeat_count+1, method)
                print _msg
                return _msg
            elif emsg.getcode() == 500:
                print _msg
                return _msg
            else:
                print emsg.read()
                raise Exception(emsg.reason)
            raise Exception('httpRequest: HTTPError - ' + str(emsg))
        except urllib2.URLError, emsg:
            raise Exception('httpRequest: URLError - ' + str(emsg))
        except Exception, emsg:
            raise Exception('httpRequest: Exception - ' + str(emsg))
    
    
    def schedule_maintenance_actions(URL, DATA):
        headers = {
            "Authorization" : "Bearer " + ACCESS_TOKEN,
            "Content-Type"  : "application/json"
        }
        try:
            response = json.loads(httpRequest(URL, DATA, headers, 0, 'GET'))
        except Exception, emsg:
            print emsg
            sys.exit(2)
    
    
    ''' Get OpsRamp access token using api key/secret for further communication '''
    def get_access_token():
        url = "https://%s/auth/oauth/token" % (API_SERVER)
    
        data = urllib.urlencode({
            "client_id"     : API_KEY,
            "client_secret" : API_SECRET,
            "grant_type"    : "client_credentials"
        })
    
        headers = {"Content-Type": "application/x-www-form-urlencoded", "Accept" : "application/json"}
        try:
            result = json.loads(httpRequest(url, data, headers, None, 'POST'))
            return result['access_token']
        except Exception as emsg:
            raise Exception("Error while getting access token - " + str(emsg))
    
    if __name__ == '__main__':
        try:
            ACCESS_TOKEN = str(get_access_token())
            
            ''' Creating a schedule maintenance window '''
            url = "https://{0}/api/v2/tenants/{1}/scheduleMaintenances".format(API_SERVER, CLIENT_ID)
            data = {
                    "name"              : "Test Maintenance from API",
                    "description"       : "Test Maintenance from API",
                    "dontRunRBA"        :"false",
                    "dontInstallPatch"  :"false", 
                    "devices"           : [{
                                            "uniqueId": "702c19c4-1991-4e99-8c5f-4104c061fe25"
                                          }],
                    "schedule"          : {
                                             "type":"One-Time",
                                             "startTime": "2016-07-07T08:21:00+0000",
                                             "endTime": "2016-07-09T08:45:00+0000",
                                             "timezone":"America/Los_Angeles"
                                          }
                    }
            
            
            ''' Searching a schedule maintenance window by name '''
            url = """https://%s/api/v2/tenants/%s/scheduleMaintenances/search?queryString=""" 
            + urllib.encode("name:Test Maintenance from API") %(API_SERVER, CLIENT_ID)
            data = None
            
            ''' Suspending a schedule maintenance window '''
            url = "https://{0}/api/v2/tenants/{1}/scheduleMaintenances/123456/suspend".format(API_SERVER, CLIENT_ID)
            data = {"pattern" : "now"}
            
            ''' Resuming a schedule maintenance window '''
            url = "https://{0}/api/v2/tenants/{1}/scheduleMaintenances/123456/resume".format(API_SERVER, CLIENT_ID)
            data = None
            
            ''' Deleting a schedule maintenance window '''
            url = "https://{0/api/v2/tenants/{1}/scheduleMaintenances/123456".format(API_SERVER, CLIENT_ID)
            data = None
            
            schedule_maintenance_actions(url, data)
        except Exception as e:
            print ("Failed - " + str(e))

  • Java

    package com.opsramp.examples.rest;
    
    import java.io.IOException;
    import java.net.URI;
    import java.net.URLEncoder;
    import java.nio.charset.StandardCharsets;
    import java.util.Date;
    
    import org.apache.http.HttpException;
    import org.apache.http.HttpHeaders;
    import org.apache.http.client.methods.CloseableHttpResponse;
    import org.apache.http.client.methods.HttpDelete;
    import org.apache.http.client.methods.HttpEntityEnclosingRequestBase;
    import org.apache.http.client.methods.HttpGet;
    import org.apache.http.client.methods.HttpPost;
    import org.apache.http.client.methods.HttpRequestBase;
    import org.apache.http.entity.ByteArrayEntity;
    import org.apache.http.entity.ContentType;
    import org.apache.http.impl.client.CloseableHttpClient;
    import org.apache.http.impl.client.HttpClients;
    import org.apache.http.util.EntityUtils;
    
    /**
     * Sample program to perform schedule maintenance actions
     */
    public class ScheduleMaintenanceActions {
    	
    	/**
    	 * Main program which performs schedule maintenance actions
    	 * @param args
    	 * @throws HttpException
    	 * @throws IOException
    	 */
    	public static void main(String[] args) throws HttpException, IOException {
    		//Replace the end point and access token accordingly
    		String ACCESS_TOKEN = "a0f46d75-534d-4180-b4ec-65a23eb1ae39";
    		
    		//Creating a schedule maintenance window
    		String ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/scheduleMaintenances";
    		String PAYLOAD = "{"name":"Test Maintenance from API","description":"Test Maintenance from API","
    				+ ""dontRunRBA":"false","dontInstallPatch":"false", "devices":[{"uniqueId":"
    				+ ""702c19c4-1991-4e99-8c5f-4104c061fe25"}],"schedule":{"type":"One-Time","startTime":"
    				+ ""2016-07-07T08:21:00+0000","endTime":"2016-07-09T08:45:00+0000","timezone":"
    				+ ""America/Los_Angeles"}}";
    		String response = invokePostRequest(ACCESS_TOKEN, ENDPOINT, PAYLOAD);
    		System.out.println(response);
    		
    		//Searching a schedule maintenance window by name
    		ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/scheduleMaintenances/search"
    			 + "?queryString=" + URLEncoder.encode("name:Test Maintenance from API", StandardCharsets.UTF_8.toString());
    		response = invokeGetRequest(ACCESS_TOKEN, ENDPOINT);
    		System.out.println(response);
    		
    		//Suspending a schedule maintenance window
    		ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/scheduleMaintenances/123456/suspend";
    		PAYLOAD = "{"pattern": "now"}";
    		response = invokePostRequest(ACCESS_TOKEN, ENDPOINT, PAYLOAD);
    		System.out.println(response);
    		
    		//Resuming a schedule maintenance window
    		ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/scheduleMaintenances/123456/resume";
    		response = invokePostRequest(ACCESS_TOKEN, ENDPOINT, null);
    		System.out.println(response);
    		
    		//Deleting a schedule maintenance window
    		ENDPOINT = "https://<api-url>/api/v2/tenants/client_99999/scheduleMaintenances/123456";
    		response = invokeDeleteRequest(ACCESS_TOKEN, ENDPOINT);
    		System.out.println(response);
    	}
    	
    	/**
    	 * Fetches data from given end point
    	 * @param accessToken
    	 * @param endPoint
    	 * @return
    	 * @throws HttpException
    	 * @throws IOException
    	 */
    	public static String invokeGetRequest(final String accessToken, final String endPoint)
    			throws HttpException, IOException {
    		return invokeRequest(accessToken, endPoint, null, new HttpGet(), 0);
    	}
    	
    	/**
    	 * Deletes data at given end point
    	 * @param accessToken
    	 * @param endPoint
    	 * @return
    	 * @throws HttpException
    	 * @throws IOException
    	 */
    	public static String invokeDeleteRequest(final String accessToken, final String endPoint)
    			throws HttpException, IOException {
    		return invokeRequest(accessToken, endPoint, null, new HttpDelete(), 0);
    	}
    	
    	/**
    	 * Posts data to given end point
    	 * @param accessToken
    	 * @param endPoint
    	 * @param payload
    	 * @return
    	 * @throws HttpException
    	 * @throws IOException
    	 */
    	public static String invokePostRequest(final String accessToken, final String endPoint,
    			final String payload) throws HttpException, IOException {
    		return invokeRequest(accessToken, endPoint, payload, new HttpPost(), 0);
    	}
    	
    	/**
    	 * Invokes an OAuth2 API request
    	 * @param accessToken
    	 * @param endPoint
    	 * @param payload
    	 * @param httpRequest
    	 * @return
    	 * @throws HttpException
    	 * @throws IOException
    	 */
    	public static String invokeRequest(final String accessToken, final String endPoint,
    			final String payload, HttpRequestBase httpRequest, final int currentRetryCount) throws HttpException, IOException {
    		CloseableHttpClient httpclient = HttpClients.custom().build();
    		try {
    			httpRequest.setURI(URI.create(endPoint));
    			httpRequest.setHeader(HttpHeaders.ACCEPT, ContentType.APPLICATION_JSON.toString());
    			httpRequest.setHeader(HttpHeaders.CONTENT_TYPE, ContentType.APPLICATION_JSON.toString());
    			httpRequest.setHeader(HttpHeaders.AUTHORIZATION, "Bearer " + accessToken);
    			if(httpRequest instanceof HttpEntityEnclosingRequestBase && payload != null) {
    				((HttpEntityEnclosingRequestBase) httpRequest)
    					.setEntity(new ByteArrayEntity(payload.getBytes(StandardCharsets.UTF_8.toString())));
    			}
    
    			System.out.println("n" + httpRequest.getRequestLine());
    			CloseableHttpResponse response = httpclient.execute(httpRequest);
    			try {
    				System.out.println("Response " + response.getStatusLine());
    				String responseBody = null;
    				if(response.getEntity() != null) { 
    					responseBody = EntityUtils.toString(response.getEntity());
    					if(response.getStatusLine().getStatusCode() == 429) {
    						if(currentRetryCount > 3) {
    							System.out.println("Retry Max-Limit(3) reached; Dropping API: " + endPoint);
    						}
    						long resetTimeInSeconds = Long.valueOf(response.getFirstHeader("X-RateLimit-Reset").getValue());
    						long retryInSec = resetTimeInSeconds - (new Date().getTime()/1000);
    						System.out.println("tNext retry in: " + retryInSec + "s" + " | " + endPoint);
    						try {
    							Thread.sleep(retryInSec*1000);
    						} catch(Exception ex) {}
    						invokeRequest(accessToken, endPoint, payload, httpRequest, currentRetryCount+1);
    					}
    				}
    				return responseBody;
    			} finally {
    				response.close();
    			}
    		} finally {
    			httpclient.close();
    		}
    	}
    }