Support > Rest Api Developers Guide > Overview > Using Logicmonitors Rest Api

Using LogicMonitor’s REST API

The LogicMonitor REST API will allow you to programmatically query and manage your LogicMonitor resources: dashboards, devices, reports, services, alerts, collectors, datasources, SDTs and more.

Note that any API calls not documented in LogicMonitor’s RPC & REST Developer Guides are considered unpublished.  We advise against using unpublished API calls as they are subject to change without notice, use of them will likely result in scripts breaking & LogicMonitor’s Technical Support will be unable to assist you with any issues you encounter.


Base URL:

The base URL for making REST API requests is: 

https://ACCOUNTNAME.logicmonitor.com/santaba/rest

Where ACCOUNTNAME is replaced with your LogicMonitor account name.

Resources

Only API calls for certain resources are available at this time. Resources will be posted to documentation as they become available. A current list of resources and methods available for v1 of LogicMonitor’s API is currently available here.

 

Versioning

LogicMonitor’s REST API is versioned as follows:

  • Semantic versioning will be used and called out in release notes, but only major version is allowed in requests (the most recent minor / patch versions will always be returned)
  • The two latest published major versions will be supported
  • Version can be specified in an ‘X-Version’ header, or in the URL as a query parameter

For example, if I include a header ‘X-Version:1’ in my request, I will get version 1.0.0  of the resource requested (assuming it is one of the latest two published versions).  If I include a query parameter v=1, e.g. /device/devices?v=1, I will get version 1.0.0 of the devices resource (assuming it is one of the latest two published versions).  If I omit the ‘X-Version’ header and v=version query parameter all together, I will get the oldest published version of the requested resource.

Currently, the following versions are supported: 

Version

Notable Information

1.x.x

2.x.x

 

Authentication

Each request sent to the LogicMonitor server must be made over HTTPS, and must also be authenticated. All data is received as JSON.  LogicMonitor’s REST API currently supports two authentication methods:

  1. Basic Authentication
  2. API Token Authentication

NOTE that Basic Authentication is only supported in v1 of the API, and may not be available with future versions of the API.  As such, we highly recommend that you make REST API requests with API Token Authentication where possible.  

 

Basic Authentication

LogicMonitor’s REST API currently supports HTTP Basic Authentication. To use HTTP Basic Authentication, each request must include an HTTP header with the following authentication information: “Authorization:Basic `echo -n username:password | base64`”

Almost all web clients support HTTP basic authentication and will construct this header for you.

Examples

In the following example, a user apiUser in account api.logicmonitor.com makes a request to update a service group 

curl -v --user 'apiUser:example' -H "Content-Type: application/json" -d '{"name":"newServiceGroup","description":"testSites","disableAlerting":false}' -X PUT "https://api.logicmonitor.com/santaba/rest/service/groups/7"

 

In the following example, a user apiUser in account api.logicmonitor.com makes a request to get all service groups 

wget --auth-no-challenge  --http-user='apiUser' --http-password='example' "https://api.logicmonitor.com/santaba/rest/service/groups"

LMv1 API Token Authentication

The recommended authentication method for LogicMonitor’s REST API is our LMv1 API Token Authentication.  This authentication method requires that with every request you include a custom HTTP header containing your API Token Access Id, a base64 encoded HMAC signature based on your API Token Access Key, and a timestamp in epoch milliseconds.

Specifically, you will need to concatenate request details to form a string, and use your Access Key to calculate the HMAC-SHA256 of that string.  You will then need to base64 encode the result.  The complete base64 encoded HMAC signature should be in the following format: 

signature = base64(HMAC-SHA256(Access Key,HTTP VERB + TIMESTAMP (in epoch milliseconds) + POST/PUT DATA (if any) + RESOURCE PATH) )

And the full authentication header must be in the following format: 

Authorization: LMv1 AccessId:Signature:Timestamp

When LogicMonitor servers receive an API request, we first ensure the specified timestamp is within 30 minutes of the current time.  If that requirement is satisfied, we retrieve the Access Key associated with the specified Access Id and compute the signature in the above format.  We then compare that signature to the signature included in the request.  If the two signatures match, the request is authenticated, but still subject to the permissions associated with the API Token (the token Access Id and Access Key must have sufficient permission to perform the requested action).  In the event that the two signatures do not match, an error will be returned.

Note: Query parameters (e.g. filter, fields, sort, ,size, etc.) are not considered part of the resource path, and should not be included in the calculation of the LMv1 authentication signature.

 

Examples:

Examples for v1 of LogicMonitor’s REST API can be found on this page.

Rate Limiting

Rate limits are imposed for requests to LogicMonitor’s REST API. Limits will be per endpoint and method combination. For example, requests to GET /device/devices may have a different limit from requests to POST /device/devices and from requests to GET /device/devices/ID/devicedatasources. Requests that are made in excess of the rate limits will get an HTTP 429 Too Many Requests & a response containing an error. Limits are not per user, and will apply to all requests made for your account.

Information about limits and proximity to limits is returned in the below response headers. This enables you to view the rate limits that will be imposed and adjust scripts as needed to work around them. 

Header

Description

X-Rate-Limit-Limit

Request limit per X-Rate-Limit-Window

X-Rate-Limit-Remaining

The number of requests left for the time window

X-Rate-Limit-Window

The rolling time window length with the unit of second

 

 We recommend basing any logic intended to work around rate limiting on the above headers and their values, as the limits are subject to change. For example, you may introduce logic in your script that, when rate limits have been met, waits 60 seconds before making another request – the following are examples of such logic in different languages:

Python

The following logic can be utilized in a loop using the requests module, and implements a simple timeout if the ‘X-Rate-Limit-Remaining’ header value gets to zero:

if (response.headers['X-Rate-Limit-Remaining'] == 0):
       window = response.headers['X-Rate-Limit-Window']
       time.sleep(float(window))

 

Ruby

The following logic can be utilized in a loop using the net http library, and implements a simple timeout if the ‘X-Rate-Limit-Remaining’ header value gets to zero:

if resp['X-Rate-Limit-Remaining'].to_i == 0
  sleep resp['X-Rate-Limit-Window'].to_i
  end

 

Groovy

The following logic can be utilized in a loop using the Apache http library, and implements a simple timeout if the ‘X-Rate-Limit-Remaining’ header value gets to zero:

remainingRequestsHeader = response.getHeaders('X-Rate-Limit-Remaining');
windowHeader = response.getHeaders('X-Rate-Limit-Window');
remainingRequests = remainingRequestsHeader[0].getValue();
window = windowHeader[0].getValue();
 
if (remainingRequests.toInteger() == 0){
    Thread.sleep(window.toInteger() * 1000);
    }

 

PowerShell

How you should work around rate limiting with PowerShell depends on how you’re making requests. The Invoke-RestMethod cmdlet throws out response headers unless an exception occurs, and as such we recommend attempting retries when an HTTP 429 is returned if using Invoke-RestMethod. For example, you could make the API request in a try catch loop, and retry if the resulting status is 429, like this:

<# Make request & retry if failed due to rate limiting #>
$Stoploop = $false
 
do {
	try {
		<# Make Request #>
		$response = Invoke-RestMethod -Uri $url -Method $httpVerb -Headers $headers
		<# Print status and body of response #>
		$status = $response.status
		$body = $response.data| ConvertTo-Json -Depth 5
		Write-Host "Status:$status"
		Write-Host "Response:$body"
		$Stoploop = $true
		}
	catch {
		if ($response.status -eq 429){
			Write-Host "Request exceeded rate limit, retrying in 60 seconds..."
			Start-Sleep -Seconds 60
			}
		else {
			Write-Host "Request failed, not as a result of rate limiting"
			$Stoploop = $true
			}
		}
	}
While ($Stoploop -eq $false)

Alternatively, you can use Invoke-WebRequest cmdlet and add logic based on the rate limiting response headers.

 

Status Codes

Status codes for v1 of LogicMonitor’s REST API can be found on this page.

More Information about REST

For more information about Representational State Transfer (REST) architecture, see this Wikipedia page.

In this Article: