API Management in the Age of DevOps

This is the first of a two-part series about API management in the age of DevOps, the challenges therein and how we’ve chosen to solve them here at LogicMonitor. Part one discusses API versioning, and part two will cover SDK and API documentation creation.

Having an API that is robust, dependable, and consistent is extremely beneficial, and pretty much a requirement when it comes to enterprise SaaS products. With the rise of DevOps and the move towards continuous delivery, it can be challenging to maintain such an API.

Balancing important details like backward compatibility with available API functionality gets harder when you’re talking about rapidly changing product features. Compensating with a shorter API release cycle usually means maintaining many versions at once, which can consume a lot of resources. Meanwhile, a longer API release cycle may mean having an API that lacks functionality, making it less valuable than it could be. Here at LogicMonitor, we faced this challenge head-on during the development of our REST API.

At the end of 2016 we announced the release of our long-awaited REST API. Given our frequent product releases, we needed to come up with a versioning plan that provided the flexibility to enable constant change without necessitating that we maintain these changes across many separate versions. Ultimately, we decided to version as follows:

Semantic versioning will be used, but only major version will be allowed in requests.
We will follow the Semantic Versioning standard. Changes to a published API version will always be backward compatible and tracked with minor and patch version increments, and all incompatible changes will be introduced in a new major version.

Minor and patch versions will be called out in the release notes, and will enable you to easily track API changes and additions. However, you’ll only need to specify the major version number in API requests. For example, a request that specifies version 1 will return the most recent version 1 of the resource. Only allowing major version in requests limits the number of times that custom scripts need to be updated to change version numbers.

Two versions of the REST API will be supported at all times.
Major versions older than the newest two will be deprecated, but not immediately removed. Supporting a set number of versions, as opposed to supporting versions for a set amount of time, makes it easier to have more frequent API releases without maintaining an unreasonable number of versions. Having more frequent API releases will enable the API to keep up with newer product features.

Version can be specified in an X-Version header, or the URL.
Allowing version in a header and the URL means that it is easy to manipulate which version of a resource you are using, and even enables you to use two versions simultaneously if desired.

Version can be specified in an X-Version header, like this:

X-Version:1

Or in the URL, like this:

/santaba/rest/device/devices?v=2

The REST API will always default to the latest published version.
This makes it easy to ensure you’re always using the most up-to date version without adding any extra steps: just omit the version from your request all together.

Aside from the obvious (and thanks to versioning, ongoing) benefit of extending the list of LogicMonitor features that can be managed programmatically, our REST API provides significant security and usability improvements in line with RESTful industry standards. If you’re not already using it, here are a few reasons why you should:

LMv1 authentication:
Our REST API LMv1 authentication utilizes a base64 encoded HMAC signature based on API token secret key, timestamp, and request details. This ensures that authentication information is sufficiently encrypted and that requests are not susceptible to replay attacks. Additionally, the use of API Tokens enables you to separately provision and revoke API and UI access, and provides more clarity around user API actions in the Audit Log.

All successful POST, PUT, PATCH, and DELETE requests are logged with username, API Token, and API action:

Failed API requests are logged with username, API Token and attempted API action:

Logical Resources:
Our REST API is logically separated into resources that conform to RESTful standards and that map closely to what is displayed in the LogicMonitor UI, making them intuitive, consistent, and easy to use.

/device/devices
/device/groups/12/devices

Result Filtering:
Our REST API includes a powerful filtering capability that can be used to sort, filter, and manipulate the size of returned results, enabling you to easily get the exact data you’re looking for without having to sift through a large set of results. For example, the following request returns the display name, id, and custom properties for all monitored EC2 devices in the AWS ap-south-1 region (Mumbai):

GET
/device/devices?filter=customProperties.name:system.categories,customProperties.value:AWS/EC2,displayName~AP-S1&fields=displayName,id,customProperties

Response:

Response Status: 200
Response Body: {
  "status" : 200,
    "errmsg" : "OK",
    "data" : {
      "total" : 1,
      "items" : [{
        "id" : 535,
        "displayName" : "AP-S1:i-072eed28687366631",
        "customProperties" : [{
          "name" : "system.categories",
          "value" : "AWS/EC2"
        }]
      }],
      "searchId" : null
    }
  }

Check out our REST API documentation for more information about resources and available methods, as well as plenty of example scripts in a variety of languages. Reach out via the feedback button in your account with questions, suggestions, or feedback about our new REST API. We’d love to hear what you think!