package module
v0.0.0-...-a6c3dda Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Sep 13, 2021 License: MIT Imports: 10 Imported by: 0


Travis CI Software License GoDoc Coverage Status

Updown Go client

This is a Go client for updown.io. Updown lets you monitor websites and online services for an affordable price.


Once you have a working Go installation locally, you can grab this package with the following command:

go get github.com/antoineaugusti/updown


Head over to the Go documentation to see available methods and models and to https://updown.io/api for the Updown API.

Creating a client

The client will be required to perform all actions against the API.

package main

import (

func main() {
    // Your API key can be retrieved at https://updown.io/settings/edit
    // You can give a custom HTTP client
    client := updown.NewClient("your-api-key", nil)
Listing all checks
result, HTTPResponse, err := client.Check.List()
Getting an Updown token for a check's alias
name := "Google"
token, err := client.Check.TokenForAlias(name)

This method returns results from a memory cache by default if it's available. The first time, a request against the API will be performed.

Getting a check by its token
token := "foo"
result, HTTPResponse, err := client.Check.Get(token)
Getting downtimes for a check
token, page := "foo", 1 // 100 results per page
result, HTTPResponse, err := client.Downtime.List(token, page)
Adding a new check
// See the struct for additional parameters
item := updown.CheckItem{URL: "https://google.fr"}
result, HTTPResponse, err := client.Check.Add(item)
Updating a check
token := "foo"
// See the struct for additional parameters
updated := updown.CheckItem{URL: "https://google.com"}
result, HTTPResponse, err := client.Check.Update(token, updated)
Removing a check
token := "foo"
result, HTTPResponse, err := client.Check.Remove(token)
Getting metrics for a check
token, group := "foo", "host"
from, to := "2016-04-01 00:00:00 +0200", "2016-04-15 00:00:00 +0200"
result, HTTPResponse, err := client.Metric.List(token, group, from, to)




This section is empty.


View Source
var ErrTokenNotFound = errors.New("Could not determine a token for the given name")

ErrTokenNotFound indicates that we cannot find a token for the given name


func CheckResponse

func CheckResponse(r *http.Response) error

CheckResponse checks the API response for errors, and returns them if present. A response is considered an error if it has a status code outside the 200 range. API error responses are expected to have either no response body, or a JSON response body that maps to ErrorResponse. Any other response body will be silently ignored.


type Cache

type Cache interface {
	Has(key string) bool
	Put(key, value string)
	Get(key string) (has bool, value string)

Cache lets you cache indefinitely values

type Check

type Check struct {
	Token             string            `json:"token,omitempty"`
	URL               string            `json:"url,omitempty"`
	Alias             string            `json:"alias,omitempty"`
	LastStatus        int               `json:"last_status,omitempty"`
	Uptime            float64           `json:"uptime,omitempty"`
	Down              bool              `json:"down"`
	DownSince         string            `json:"down_since,omitempty"`
	Error             string            `json:"error,omitempty"`
	Period            int               `json:"period,omitempty"`
	Apdex             float64           `json:"apdex_t,omitempty"`
	Enabled           bool              `json:"enabled"`
	Published         bool              `json:"published"`
	LastCheckAt       string            `json:"last_check_at,omitempty"`
	NextCheckAt       string            `json:"next_check_at,omitempty"`
	FaviconURL        string            `json:"favicon_url,omitempty"`
	SSL               SSL               `json:"ssl,omitempty"`
	StringMatch       string            `json:"string_match,omitempty"`
	MuteUntil         string            `json:"mute_until,omitempty"`
	DisabledLocations []string          `json:"disabled_locations,omitempty"`
	CustomHeaders     map[string]string `json:"custom_headers,omitempty"`

Check represents a check performed by Updown on a regular basis

type CheckItem

type CheckItem struct {
	// The URL you want to monitor
	URL string `json:"url,omitempty"`
	// Interval in seconds (30, 60, 120, 300 or 600)
	Period int `json:"period,omitempty"`
	// APDEX threshold in seconds (0.125, 0.25, 0.5 or 1.0)
	Apdex float64 `json:"apdex_t,omitempty"`
	// Is the check enabled
	Enabled bool `json:"enabled"`
	// Shall the status page be public
	Published bool `json:"published"`
	// Human readable name
	Alias string `json:"alias,omitempty"`
	// Search for this string in the page
	StringMatch string `json:"string_match,omitempty"`
	// Mute notifications until given time, accepts a time, 'recovery' or 'forever'
	MuteUntil string `json:"mute_until,omitempty"`
	// Disabled monitoring locations. It's an array of abbreviated location names
	DisabledLocations []string `json:"disabled_locations,omitempty"`
	// The HTTP headers you want in updown requests
	CustomHeaders map[string]string `json:"custom_headers,omitempty"`

CheckItem represents a new check you want to be performed by Updown

type CheckService

type CheckService struct {
	// contains filtered or unexported fields

CheckService interacts with the checks section of the API

func (*CheckService) Add

func (s *CheckService) Add(data CheckItem) (Check, *http.Response, error)

Add adds a new check you want to be performed

func (*CheckService) Get

func (s *CheckService) Get(token string) (Check, *http.Response, error)

Get gets a single check by its token

func (*CheckService) List

func (s *CheckService) List() ([]Check, *http.Response, error)

List lists all the checks

func (*CheckService) Remove

func (s *CheckService) Remove(token string) (bool, *http.Response, error)

Remove removes a check from Updown by its token

func (*CheckService) TokenForAlias

func (s *CheckService) TokenForAlias(name string) (string, error)

TokenForAlias finds the Updown token for a check's alias

func (*CheckService) Update

func (s *CheckService) Update(token string, data CheckItem) (Check, *http.Response, error)

Update updates a check performed by Updown

type Client

type Client struct {

	// Base URL for API requests
	BaseURL *url.URL

	// User agent for client
	UserAgent string

	// APIKey to use for the API
	APIKey string

	// Services used for communications with the API
	Check    CheckService
	Downtime DowntimeService
	Metric   MetricService
	Node     NodeService
	Webhook  WebhookService
	// contains filtered or unexported fields

Client manages communication the API

func NewClient

func NewClient(apiKey string, httpClient *http.Client) *Client

NewClient returns a new API client.

func (*Client) Do

func (c *Client) Do(req *http.Request, v interface{}) (*http.Response, error)

Do sends an API request and returns the API response. The API response is JSON decoded and stored in the value pointed to by v, or returned as an error if an API error has occurred. If v implements the io.Writer interface, the raw response will be written to v, without attempting to decode it.

func (*Client) NewRequest

func (c *Client) NewRequest(method, urlStr string, body interface{}) (*http.Request, error)

NewRequest creates an API request. A relative URL can be provided in urlStr, which will be resolved to the BaseURL of the Client. Relative URLS should always be specified without a preceding slash. If specified, the value pointed to by body is JSON encoded and included in as the request body.

type Downtime

type Downtime struct {
	Error     string `json:"error,omitempty"`
	StartedAt string `json:"started_at,omitempty"`
	EndedAt   string `json:"ended_at,omitempty"`
	Duration  int    `json:"duration,omitempty"`

Downtime represents a downtime period for a check

type DowntimeService

type DowntimeService struct {
	// contains filtered or unexported fields

DowntimeService interacts with the downtimes section of the API

func (*DowntimeService) List

func (s *DowntimeService) List(token string, pageNb int) ([]Downtime, *http.Response, error)

List lists all known downtimes for a check

type ErrorResponse

type ErrorResponse struct {
	// HTTP response that caused this error
	Response *http.Response

	// Error message
	Message string

An ErrorResponse reports the error caused by an API request

func (*ErrorResponse) Error

func (r *ErrorResponse) Error() string

type Host

type Host struct {
	IP          string `json:"ip,omitempty"`
	City        string `json:"city,omitempty"`
	Country     string `json:"country,omitempty"`
	CountryCode string `json:"country_code,omitempty"`

Host represents the host where the check was made

type IPs

type IPs []string

IPs represents IP addresses in v4 or v6

type MemoryCache

type MemoryCache struct {
	// contains filtered or unexported fields

MemoryCache is a cache that works in memory

func NewMemoryCache

func NewMemoryCache() *MemoryCache

NewMemoryCache creates a new memory cache

func (*MemoryCache) Get

func (c *MemoryCache) Get(key string) (has bool, value string)

Get gets a value from the cache by its key and tells if it was found or not

func (*MemoryCache) Has

func (c *MemoryCache) Has(key string) bool

Has determines if we can find in the cache a key for the given value

func (*MemoryCache) Put

func (c *MemoryCache) Put(key, value string)

Put associates a key to a given value in the cache

type MetricItem

type MetricItem struct {
	Apdex    float64  `json:"apdex,omitempty"`
	Requests Requests `json:"requests,omitempty"`
	Timings  Timings  `json:"timings,omitempty"`
	Host     Host     `json:"host,omitempty"`

MetricItem is basically the core metric

type MetricService

type MetricService struct {
	// contains filtered or unexported fields

MetricService interacts with the metrics section of the API

func (*MetricService) List

func (s *MetricService) List(token, group, from, to string) (Metrics, *http.Response, error)

List lists metrics available for a check identified by a taken, grouped by the given group (host|time) over a period

type Metrics

type Metrics map[string]MetricItem

Metrics represents multiple metrics

type NodeDetails

type NodeDetails struct {
	IP          string `json:"ip,omitempty"`
	IP6         string `json:"ip6,omitempty"`
	City        string `json:"city,omitempty"`
	Country     string `json:"country,omitempty"`
	CountryCode string `json:"country_code,omitempty"`

NodeDetails gives information about a node

type NodeService

type NodeService struct {
	// contains filtered or unexported fields

NodeService interacts with the nodes section of the API

func (*NodeService) List

func (s *NodeService) List() (Nodes, *http.Response, error)

List gets the nodes performing checks

func (*NodeService) ListIPv4

func (s *NodeService) ListIPv4() (IPs, *http.Response, error)

ListIPv4 gets the list of IPv4 performing checks

func (*NodeService) ListIPv6

func (s *NodeService) ListIPv6() (IPs, *http.Response, error)

ListIPv6 gets the list of IPv6 performing checks

type Nodes

type Nodes map[string]NodeDetails

Nodes represents multiple nodes

type Requests

type Requests struct {
	Samples      int          `json:"samples,omitempty"`
	Failures     int          `json:"failures,omitempty"`
	Satisfied    int          `json:"satisfied,omitempty"`
	Tolerated    int          `json:"tolerated,omitempty"`
	ResponseTime ResponseTime `json:"by_response_time,omitempty"`

Requests gives statistics about requests made to check the status

type ResponseTime

type ResponseTime struct {
	Under125  int `json:"under125,omitempty"`
	Under250  int `json:"under250,omitempty"`
	Under500  int `json:"under500,omitempty"`
	Under1000 int `json:"under1000,omitempty"`
	Under2000 int `json:"under2000,omitempty"`
	Under4000 int `json:"under4000,omitempty"`

ResponseTime represents the response times in milliseconds

type SSL

type SSL struct {
	TestedAt string `json:"tested_at,omitempty"`
	Valid    bool   `json:"valid,omitempty"`
	Error    string `json:"error,omitempty"`

SSL represents the SSL section of a check

type Timings

type Timings struct {
	Redirect   int `json:"redirect,omitempty"`
	NameLookup int `json:"namelookup,omitempty"`
	Connection int `json:"connection,omitempty"`
	Handshake  int `json:"handshake,omitempty"`
	Response   int `json:"response,omitempty"`
	Total      int `json:"total,omitempty"`

Timings represents the amount of time taken by each part of the connection

type Webhook

type Webhook struct {
	ID  string `json:"id,omitempty"`
	URL string `json:"url,omitempty"`

Webhook represents a webhook called by Updown on any event

type WebhookService

type WebhookService struct {
	// contains filtered or unexported fields

WebhookService interacts with the webhooks section of the API

func (*WebhookService) Add

func (s *WebhookService) Add(webhook Webhook) (Webhook, *http.Response, error)

Add adds a new webhook you want to be performed

func (*WebhookService) List

func (s *WebhookService) List() ([]Webhook, *http.Response, error)

List lists all the webhooks

func (*WebhookService) Remove

func (s *WebhookService) Remove(id string) (bool, *http.Response, error)

Remove removes a webhook from Updown by its ID

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL