Site24x7client is an un-official Site24x7 API Ruby client, mainly for usage with simple geo-monitors.

It supports many of the major features of the API with a simple Ruby interface (for API v2). You can set up monitors, add users, and retrieve status data easily.

Note: this is v0.1.0, there are many basic features left to complete (comprehensive tests, summary reports, easy to use thresholds, etc.). Accepting PRs for needed functionality!

Important: Thanks to DigitalOcean's DropletKit and ResourceKit, as much was borrowed re: API client style.

Add this line to your application's Gemfile:

gem "site24x7client", :git => "https://github.com/danvideo/site24x7client"

And then execute:

$ bundle install

Or (when added to RubyGems) install it as:

$ gem install site24x7client

Ruby version note: Site24x7client was tested on v2.4, but you should be able to use various 2.0+ flavors without much difficulty.

Of course you'll need a Site24x7 Account to get started (they offer free ones), and then generate an access token: https://www.site24x7.com/app/client#/admin/developer/api

$ export SITE24X7_TOKEN=*TOKEN_HERE*

To start, retrieve a client instance with your access token:

require 'site24x7client'
client = Site24x7client::Client.new(access_token: ENV["SITE24X7_TOKEN"])

To perform a GET request to list particular resources, try the following:

monitors              = client.monitors.all
monitor_groups        = client.monitor_groups.all
user_groups           = client.user_groups.all
users                 = client.users.all
location_profiles     = client.location_profiles.all
threshold_profiles    = client.threshold_profiles.all
notification_profiles = client.notification_profiles.all

To find a specific monitor by id or name:

client.monitors.find(id: "12345678901234567890")
client.monitors.find_by_name(name: "Name-Here")

Note: when using find_by_name you must use %20 as a substitute for spaces as this name will become part of the URL request:

client.monitors.find_by_name(name: 	"If%20There%20Are%20Spaces")

To pull up-to-date location data on monitor statuses, and then to parse specifically by location of Website Monitors, i.e. type: "URL"

current_status = client.current_status.all
current_status.url_locations

To experiment with the code, run bundle console for an interactive prompt.

It should allow you to run an interactive REPL session to test out gem functionality.

In an ideal world there would be lots of info about tests here as well :(

This describes how the Site24x7client gem could interact with a larger system architecture. Having easy-to-use access to the Site24x7 API can quickly allow you to create services that pull data for metrics or add new monitors as they go live.

Site24x7client follows a strict design pattern of resources as methods on the client. For example, call the client and then its method/resource:

client = Site24x7client::Client.new(access_token: 'YOUR_TOKEN')
client.monitors #=> MonitorsResource

Site24x7client will return Ruby objects that contain the information provided by the API. For example:

client = Site24x7client::Client.new(access_token: 'YOUR_TOKEN')
client.monitors.all
# => [ Site24x7client::Monitor(id: 123, display_name: 'example.com', ...), 
Site24x7client::Monitor(id: 456, name: 'test.com', ...) ]

In most cases this is true, say for create or update, POST/PUT, but for others, a response of TRUE upon success may be default.

To save objects, instantiate the object and persist it using the resource objects. As an example:

client = Site24x7client::Client.new(access_token: 'YOUR_TOKEN')
monitor = Site24x7client::Monitor.new(display_name: "NYC-example.com", type: "URL", website: "https://example.com", etc...)
created = client.monitors.create(monitor)
# => Site24x7client::Monitor(id: 1231, display_name: 'NYC-example.com', ...)

To retrieve objects, you can perform this type of action on the resource (if the API supports it):

client = Site24x7client::Client.new(access_token: 'YOUR_TOKEN')
monitor = client.monitors.find(id: 123)
# => Site24x7client::Monitor(id: 1231, display_name: 'NYC-example.com', ...)

monitor = Site24x7client::Monitor.new({
	"monitor_id": "",
	"display_name": "this is a new monitor",
	"type": "URL",
	"website": "http//www.example.com",
	"check_frequency": 1,
	"timeout": 10,
	"location_profile_id": "need-valid-id",
	"notification_profile_id": "need-valid-id",
	"threshold_profile_id": "need-valid-id",
	"user_group_ids": ["need-valid-id"],
	"http_method": "G",
	"use_ipv6": false,
	"matching_keyword": {
		"value": "",
		"severity": 0
	},
	"monitor_groups": ["need-valid-id"],
	"up_status_codes": "200"
})

user = Site24x7client::User.new(
{
	"display_name": "NAME_HERE",
	"email_address": "name@example.com",
	"user_role": 1,
	"notify_medium": [1],
	"user_groups": ["GROUP_ID1", "GROUP_ID2"],
	"alert_settings": {
		"email_format": 0,
		"dont_alert_on_days": [0, 1, 2, 3, 4, 5, 6],
		"down": [1],
		"trouble": [1],
		"up": [1]
	}
})

Instantiate the client:

client = Site24x7client::Client.new(access_token: 'TOKEN')

Actions supported:

• client.monitors.all
• client.monitors.find(id: "id")
• client.monitors.find_by_name(name: "name")
• client.monitors.create(Monitor.new(params))
• client.monitors.update(Monitor, id: "id")
• client.monitors.delete(id: "id")
• client.monitors.delete_by_name(name: "name")
• client.monitors.delete_multiple(monitor_ids: "monitor_id,monitor_id")
• client.monitors.activate(id: "id")
• client.monitors.suspend(id: "id")

Actions supported:

• client.users.all
• client.users.find(id: "id")
• client.users.create(User.new(params))
• client.users.update(User, id: "id")
• client.users.delete(id: "id")

Actions supported:

• client.current_status.all
• client.current_status.find(id: "id")

All the methods for querying current status by Monitor Type are supported. For more info see "Types" on Site24x7's constants.
A few examples though:

• client.current_status.urls
• client.current_status.homepages
• client.current_status.realbrowsers

These are parsing methods after getting all monitor_statuses:

• current_status = client.current_status.all
• current_status.web
• current_status.url
• current_status.url_locations
• current_status.advanced
• current_status.to_groups
• current_status.groups
• current_status.group_locations
• current_status.all_monitors
• current_status.all_locations

Actions supported:

• client.location_profiles.all
• client.location_profiles.find(id: "id")
• client.location_profiles.create(LocationProfile.new(params))
• client.location_profiles.update(LocationProfile, id: "id")
• client.location_profiles.delete(id: "id")

Actions supported:

• client.notification_profiles.all
• client.notification_profiles.find(id: "id")
• client.notification_profiles.create(NotificationProfile.new(params))
• client.notification_profiles.update(NotificationProfile, id: "id")
• client.notification_profiles.delete(id: "id")

Actions supported:

• client.threshold_profiles.all
• client.threshold_profiles.find(id: "id")
• client.threshold_profiles.create(ThresholdProfile.new(params))
• client.threshold_profiles.update(ThresholdProfile, id: "id")
• client.threshold_profiles.delete(id: "id")

Actions supported:

• client.monitor_groups.all
• client.monitor_groups.find(id: "id")
• client.monitor_groups.create(MonitorGroup.new(params))
• client.monitor_groups.update(MonitorGroup, id: "id")
• client.monitor_groups.delete(id: "id")

Actions supported:

• client.user_groups.all
• client.user_groups.find(id: "id")
• client.user_groups.create(UserGroup.new(params))
• client.user_groups.update(UserGroup, id: "id")
• client.user_groups.delete(id: "id")

Actions supported:

• c.audit_logs.all(params: Site24x7client::AuditLog.one_hour_ago)
• c.audit_logs.all(params: Site24x7client::AuditLog.one_week_ago)
• c.audit_logs.all(params: Site24x7client::AuditLog.one_month_ago)
• c.audit_logs.all(params: Site24x7client::AuditLog.one_year_ago)

Bug reports and pull requests are welcome!

1. Fork it https://github.com/danvideo/site24x7client/fork
2. Create your feature branch git checkout -b my-new-feature
3. Commit your changes git commit -am 'Add some feature'
4. Push to the branch git push origin my-new-feature
5. Create a new Pull Request

The gem is available as open source under the terms of the MIT License.