• Stars
    star
    57
  • Rank 522,947 (Top 11 %)
  • Language
    Go
  • License
    MIT License
  • Created over 6 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Client library for UptimeRobot v2 API

Go Reference Go Report Card Mentioned in Awesome Go Tests

uptimerobot

uptimerobot is a Go library and command-line client for the Uptime Robot website monitoring service. It allows you to search for existing monitors, delete monitors, create new monitors, and also inspect your account details and alert contacts.

Installing the command-line client

To install the client binary, run:

go get -u github.com/bitfield/uptimerobot

Running the command-line client in Docker

To use the client in a Docker container, run:

docker container run bitfield/uptimerobot

Using the command-line client

To see help on using the client, run:

uptimerobot -h

Setting your API key

To use the client with your Uptime Robot account, you will need the Main API Key for the account. Go to the Uptime Robot Settings page and click 'Show/hide it' under the 'Main API Key' section.

There are three ways to pass your API key to the client: in a config file, in an environment variable, or on the command line.

In a config file

The uptimerobot client will read a config file named .uptimerobot.yaml (or .uptimerobot.json, or any other extension that Viper supports) in your home directory, or in the current directory.

For example, you can put your API key in the file $HOME/.uptimerobot.yaml, and uptimerobot will find and read it automatically (replace XXX with your own API key):

apiKey: XXX

In an environment variable

uptimerobot will look for the API key in an environment variable named UPTIMEROBOT_API_KEY:

export UPTIMEROBOT_API_KEY=XXX
uptimerobot ...

(For historical reasons, the variable can also be named UPTIMEROBOT_APIKEY.)

On the command line

You can also pass your API key to the uptimerobot client using the --apiKey flag like this:

uptimerobot --apiKey XXX ...

Testing your configuration

To test that your API key is correct and uptimerobot is reading it properly, run:

uptimerobot account

You should see your account details listed:

Email: [email protected]
Monitor limit: 300
Monitor interval: 1
Up monitors: 208
Down monitors: 2
Paused monitors: 0

If you get an error message, double-check you have the correct API key:

2018/07/12 16:04:26 API error: {
 "message": "api_key not found.",
 "parameter_name": "api_key",
 "passed_value": "XXX",
 "type": "invalid_parameter"
}

Listing contacts

The uptimerobot contacts command will list your configured alert contacts by ID number:

uptimerobot contacts
ID: 0102759
Name: Jay Random
Type: 2
Status: 2
Value: [email protected]

ID: 2053888
Name: Slack
Type: 11
Status: 2
Value: https://hooks.slack.com/services/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

This will be useful when you create a new monitor, because you can add the contact IDs which should be alerted when the check fails (see 'Creating a new monitor' below).

Listing or searching for monitors

Use uptimerobot search to list all monitors whose 'friendly name' or check URL match a certain string:

uptimerobot search www.example.com
ID: 780689017
Name: Example.com website
URL: https://www.example.com/
Status: Up
Type: HTTP

(Use uptimerobot monitors to list all existing monitors.)

If there are no monitors found matching your search, the exit status of the command will be 1. Otherwise it will be 0. (If you're checking whether a monitor already exists before creating it, try the ensure command instead.)

Deleting monitors

Note the ID number of the monitor you want to delete, and run uptimerobot delete:

uptimerobot delete 780689017
Monitor ID 780689017 deleted

Pausing or starting monitors

Note the ID number of the monitor you want to pause, and run uptimerobot pause:

uptimerobot pause 780689017
Monitor ID 780689017 paused

To resume a paused monitor, run uptimerobot start with the monitor ID:

uptimerobot start 780689017
Monitor ID 780689017 started

Creating a new monitor

Run uptimerobot new URL NAME to create a new monitor:

uptimerobot new https://www.example.com/ "Example.com website"
New monitor created with ID 780689018

To create a new monitor with alert contacts configured, use the -c flag followed by a comma-separated list of contact IDs, with no spaces:

uptimerobot new -c 0102759,2053888 https://www.example.com/ "Example.com website"
New monitor created with ID 780689019

Ensuring a monitor exists

Sometimes you want to create a new monitor only if a monitor doesn't already exist for the same URL. This is especially useful in automation.

To do this, run uptimerobot ensure URL NAME:

uptimerobot ensure https://www.example.com/ "Example.com website"
Monitor ID 780689018 ensured

If the monitor doesn't already exist, it will be created.

You can use the -c flag to add alert contacts, just as for the uptimerobot new command.

Checking the version number

To see what version of the command-line client you're using, run uptimerobot version.

Viewing debug output

When things aren't going quite as they should, you can add the --debug flag to your command line to see a dump of the HTTP request and response from the server. This is helpful if you want to report problems with the client, for example.

Using the Go library

If the command-line client doesn't do quite what you need, or if you want to use Uptime Robot API access in your own programs, import the library using:

import "github.com/bitfield/uptimerobot/pkg"

Create a new Client object by calling uptimerobot.New() with an API key:

client = uptimerobot.New(apiKey)

Once you have a client, you can use it to call various Uptime Robot API features:

monitors, err := client.AllMonitors()
if err != nil {
        log.Fatal(err)
}
for _, m := range monitors {
        fmt.Println(m)
        fmt.Println()
}

Most API operations use the Monitor struct, which looks like this:

type Monitor struct {
	ID           int64  `json:"id,omitempty"`
        FriendlyName string `json:"friendly_name"`
        URL          string `json:"url"`
        ...
}

For example, to delete a monitor, find the ID of the monitor you want to delete, and pass it to DeleteMonitor():

if err := client.DeleteMonitor(780689017); err != nil {
        log.Fatal(err)
}

To call an Uptime Robot API verb not implemented by the uptimerobot library, you can use the MakeAPICall() method directly, passing it some suitable JSON data:

r := uptimerobot.Response{}
data := []byte(fmt.Sprintf("{\"id\": \"%d\"}", m.ID))
if err := client.MakeAPICall("deleteMonitor", &r, data); err != nil {
    log.Fatal(err)
}
fmt.Println(r.Monitor.ID)

The API response is returned in the Response struct. If the call fails, MakeAPICall() will return the error message. Otherwise, the requested data will be available in the appropriate field of the Response struct:

type Response struct {
        Stat          string         `json:"stat"`
        Account       Account        `json:"account"`
        Monitors      []Monitor      `json:"monitors"`
        Monitor       Monitor        `json:"monitor"`
        AlertContacts []AlertContact `json:"alert_contacts"`
        Error         Error          `json:"error"`
}

For example, when creating a new monitor, the ID of the created monitor will be returned as r.Monitor.ID.

If things aren't working as you expect, you can use the debug facility to dump the raw request and response data from every API call. To do this, set the environment variable UPTIMEROBOT_DEBUG, which will dump debug information to the standard output, or set client.Debug to any io.Writer to send output to that writer.

Here's an example of the debug output shown when creating a new monitor:

POST /v2/newMonitor HTTP/1.1
Host: api.uptimerobot.com
User-Agent: Go-http-client/1.1
Content-Length: 221
Content-Type: application/json
Accept-Encoding: gzip

{
  "alert_contacts": "0335551_0_0-2416450_0_0",
  "api_key": "XXX",
  "format": "json",
  "friendly_name": "Example check",
  "port": 443,
  "type": 1,
  "url": "https://www.example.com"
}

HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Cf-Ray: 505422654b04dbf3-LHR
Content-Type: application/json; charset=utf-8
Date: Mon, 12 Aug 2019 17:22:57 GMT
Etag: W/"33-NlNt8dOhQvno31TtQYsI0xTJ9w"
Expect-Ct: max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
Server: cloudflare
Set-Cookie: __cfduid=d9ec99b8a777d9f806956432718fb5c81565630577; expires=Tue, 11-Aug-20 17:22:57 GMT; path=/; domain=.uptimerobot.com; HttpOnly
Vary: Accept-Encoding

{"stat":"ok","monitor":{"id":783263671,"status":1}}

Bugs and feature requests

If you find a bug in the uptimerobot client or library, please open an issue. Similarly, if you'd like a feature added or improved, let me know via an issue.

Not all the functionality of the Uptime Robot API is implemented yet.

Pull requests welcome!

More Repositories

1

script

Making it easy to write shell-like scripts in Go
Go
5,457
star
2

ftl-fundamentals

Exercises in the fundamentals of Go, to accompany the book 'For the Love of Go', by John Arundel.
Go
142
star
3

gotestdox

A tool for formatting Go test results as readable documentation
Go
112
star
4

ftl-code

Code listings accompanying the 'For the Love of Go' book
Go
96
star
5

tpg-tools

Code examples from the book 'The Power of Go: Tools'
Go
68
star
6

kg-generics

Exercises and solutions from the book 'Know Go: Generics'
Go
67
star
7

gmachine

A set of Go exercises implementing a virtual computer system
Go
56
star
8

puppet-beginners-guide-3

Example code repo for the Puppet 5 Beginner's Guide, 3rd Edition
Shell
44
star
9

puppet-beginners-guide

Play along with the Puppet Beginner's Guide, 2nd edition!
37
star
10

tpg-tools2

Code examples from the book 'The Power of Go: Tools'
Go
26
star
11

tpg-tests

Code examples from the book 'The Power of Go: Tests'
Go
17
star
12

qrand

Quantum randomness source using the ANU hardware QRNG
Go
15
star
13

ftl-data

Exercises to accompany the book 'For the Love of Go: Data', by John Arundel.
Go
15
star
14

terraform-provider-checkly

A Terraform provider for the Checkly monitoring service
Go
15
star
15

control-repo-3

A complete example Puppet infrastructure
Shell
13
star
16

control-repo

A complete example Puppet infrastructure
Puppet
13
star
17

weaver

A simple link checker in Go
Go
10
star
18

kg-generics2

Exercises and solutions from the book 'Know Go: Generics' (2024 edition)
Go
10
star
19

procrastiproxy

A project template for a blocking proxy server in Go.
Go
9
star
20

shellspy

A project template for a shell transcript recorder in Go
Go
9
star
21

weather

A project template for a weather client in Go
Go
9
star
22

morningpost

A project template for a personalised newspaper in Go
Go
8
star
23

know-go

Exercises and solutions from the book 'Know Go'
Go
6
star
24

lander

Crowdsourced lunar lander game written by students, faculty, and friends at the Bitfield Institute of Technology
Go
6
star
25

vim-gitgo

Golang colorscheme for Vim, inspired by GitHub
Vim Script
6
star
26

key

A password strength checking library in Go
Go
6
star
27

checkly

A Go library for use with the Checkly API
Go
6
star
28

cookbook

Shell
5
star
29

eg-crypto

Go code samples and exercises for the book 'Explore Go: Cryptography'
Go
4
star
30

checkd

A Go library for writing programs which collect metrics
Go
4
star
31

tsr-tools

Code examples, exercises, and solutions from the book 'The Secrets of Rust: Tools'
Rust
3
star
32

habit

A project template for a habit tracker in Go
Go
3
star
33

cronrun

A library for parsing crontab strings
Go
3
star
34

grink

A tool to check web links in Markdown files
Rust
3
star
35

shift

A simple shift cipher demonstration in Go
Go
2
star
36

rskey

A simple key-value store in Rust
Rust
2
star
37

adventure

A simple adventure game challenge in Go
Go
2
star
38

checklist

Turn a text file into an interactive checklist
Go
2
star
39

terraform-ci

A single container image for CI-based Terraform testing
Dockerfile
2
star
40

cargo-testdox

Formats Rust test results as readable documentation
Rust
2
star
41

rmachine

A simple RISC CPU for emulation exercises
2
star
42

checkepub

A Go library and CLI tool for validating EPUB files using the HamePub Lint API
Go
2
star
43

linkcheck

A project template for a website link checker in Go.
Go
2
star
44

options

Simple example of functional options in Go
Go
2
star
45

pbg_ntp

Example Puppet module to manage NTP
Puppet
2
star
46

terraform-provider-uptimerobot

A Terraform provider for the Uptime Robot website monitoring service
Go
2
star
47

trm32

A reference emulator in Rust for the TRM32 architecture
Rust
2
star
48

microbit-clock

A digital clock in Rust for the BBC micro:bit
Rust
2
star
49

sicp

Scheme exercises in the 'Structure & Interpretation of Computer Programs' book
Scheme
1
star
50

txtar-c

A tool for creating txtar archives
Go
1
star
51

microbit-beachball

A Rust project for the BBC micro:bit
Rust
1
star
52

tcptest

Go
1
star
53

yijing

A library and command-line tool for consulting the I Ching
Go
1
star
54

embed

Go
1
star
55

edger

Test your Dockerfiles against the latest version of base images
Go
1
star
56

love

Go code samples and exercises for the book 'For the Love of Go'
Go
1
star
57

gcp

A simple client library for accessing Google Cloud resources
Go
1
star
58

Powering-up-with-Puppet

Template and sample code for getting started using Puppet
1
star