updown

package module
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Dec 23, 2025 License: MIT Imports: 11 Imported by: 0

README

Updown Go Client

CI Release Go Reference

A Go client library for updown.io - a simple and affordable website monitoring service.

Fork Notice

This project was forked from antoineaugusti/updown by SERGO GmbH.

We are actively modernizing and updating this module to support the current updown.io API implementation, including:

  • Support for all check types (http, https, icmp, tcp, tcps)
  • HTTP verb configuration (GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS)
  • HTTP body for POST/PUT/PATCH requests
  • Recipients API support
  • Modern Go version (1.24+)

Contributing

We'd love to see you contribute! Whether it's:

  • Reporting bugs or suggesting features via Issues
  • Submitting Pull Requests with improvements or fixes
  • Improving documentation

All contributions are welcome!

Installation

go get github.com/sergo-techhub/updown

Quick Start

package main

import (
    "fmt"
    "github.com/sergo-techhub/updown"
)

func main() {
    // Your API key from https://updown.io/settings/edit
    client := updown.NewClient("your-api-key", nil)

    // List all checks
    checks, _, err := client.Check.List()
    if err != nil {
        panic(err)
    }

    for _, check := range checks {
        fmt.Printf("%s: %s\n", check.Alias, check.URL)
    }
}

Usage Examples

Creating a Client
client := updown.NewClient("your-api-key", nil)
Working with Checks
// List all checks
checks, _, err := client.Check.List()

// Get a check by token
check, _, err := client.Check.Get("token")

// Get token for a check alias
token, err := client.Check.TokenForAlias("My Website")

// Create a new HTTP check
item := updown.CheckItem{
    URL:   "https://example.com",
    Alias: "Example Website",
}
check, _, err := client.Check.Add(item)

// Create an ICMP ping check
item := updown.CheckItem{
    URL:  "192.168.1.1",
    Type: "icmp",
}
check, _, err := client.Check.Add(item)

// Create a TCP port check
item := updown.CheckItem{
    URL:  "tcp://db.example.com:5432",
    Type: "tcp",
}
check, _, err := client.Check.Add(item)

// Create an HTTP POST check
item := updown.CheckItem{
    URL:      "https://api.example.com/health",
    HttpVerb: "POST",
    HttpBody: `{"check": true}`,
    CustomHeaders: map[string]string{
        "Content-Type": "application/json",
    },
}
check, _, err := client.Check.Add(item)

// Update a check
updated := updown.CheckItem{URL: "https://new-url.example.com"}
check, _, err := client.Check.Update("token", updated)

// Delete a check
deleted, _, err := client.Check.Remove("token")
Working with Recipients
// List all recipients
recipients, _, err := client.Recipient.List()

// Create a recipient
item := updown.RecipientItem{
    Type:  updown.RecipientTypeEmail,
    Value: "alerts@example.com",
}
recipient, _, err := client.Recipient.Add(item)

// Delete a recipient
deleted, _, err := client.Recipient.Remove("recipient-id")
Working with Downtimes
// List downtimes for a check (paginated, 100 per page)
downtimes, _, err := client.Downtime.List("token", 1)
Working with Metrics
token := "your-check-token"
group := "host"
from := "2024-01-01 00:00:00 +0000"
to := "2024-01-31 23:59:59 +0000"
metrics, _, err := client.Metric.List(token, group, from, to)
Working with Nodes
// Get IPv4 addresses of monitoring nodes
ipv4, _, err := client.Node.ListIPv4()

// Get IPv6 addresses of monitoring nodes
ipv6, _, err := client.Node.ListIPv6()

API Reference

For the complete updown.io API documentation, visit: https://updown.io/api

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Documentation

Index

Constants

This section is empty.

Variables

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

Functions

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.

Types

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"`
	Type              string            `json:"type,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"`
	HttpVerb          string            `json:"http_verb,omitempty"`
	HttpBody          string            `json:"http_body,omitempty"`
	RecipientIDs      []string          `json:"recipients,omitempty"`
}

Check represents a check performed by Updown on a regular basis

type CheckItem 

type CheckItem struct {
	// The type of check (http, https, icmp, tcp, tcps)
	Type string `json:"type,omitempty"`
	// The URL you want to monitor
	URL string `json:"url,omitempty"`
	// Interval in seconds (15, 30, 60, 120, 300, 600, 1800 or 3600)
	Period int `json:"period,omitempty"`
	// APDEX threshold in seconds (0.125, 0.25, 0.5, 1.0, 2.0, 4.0 or 8.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"`
	// HTTP verb (GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS)
	HttpVerb string `json:"http_verb,omitempty"`
	// HTTP body for POST/PUT/PATCH requests
	HttpBody string `json:"http_body,omitempty"`
	// IDs of the recipients related to the check
	RecipientIDs []string `json:"recipients,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

	// SkipCache adds a cache-busting parameter to GET requests
	// to bypass the API's 30-second cache
	SkipCache bool

	// Services used for communications with the API
	Check      CheckService
	Downtime   DowntimeService
	Metric     MetricService
	Node       NodeService
	Webhook    WebhookService
	Recipient  RecipientService
	StatusPage StatusPageService
	// 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 Recipient 

type Recipient struct {
	ID    string        `json:"id,omitempty"`
	Type  RecipientType `json:"type,omitempty"`
	Value string        `json:"value,omitempty"`
	Name  string        `json:"name,omitempty"`
}

Recipient represents a recipient from the API

type RecipientItem 

type RecipientItem struct {
	Type  RecipientType `json:"type,omitempty"`
	Value string        `json:"value,omitempty"`
	Name  string        `json:"name,omitempty"`
}

RecipientItem represents a recipient to create

type RecipientService 

type RecipientService struct {
	// contains filtered or unexported fields
}

RecipientService interacts with the recipients API

func (*RecipientService) Add 

func (s *RecipientService) Add(data RecipientItem) (Recipient, *http.Response, error)

Add creates a new recipient

func (*RecipientService) List 

func (s *RecipientService) List() ([]Recipient, *http.Response, error)

List lists all recipients

func (*RecipientService) Remove 

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

Remove deletes a recipient by ID

type RecipientType 

type RecipientType string

RecipientType represents the type of a recipient 

const (
	RecipientTypeEmail    RecipientType = "email"
	RecipientTypeSMS      RecipientType = "sms"
	RecipientTypeTelegram RecipientType = "telegram"
	RecipientTypeSlack    RecipientType = "slack"
	RecipientTypeWebhook  RecipientType = "webhook"
	RecipientTypeZapier   RecipientType = "zapier"
)

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 StatusPage 

type StatusPage struct {
	Token       string   `json:"token,omitempty"`
	URL         string   `json:"url,omitempty"`
	Name        string   `json:"name,omitempty"`
	Description string   `json:"description,omitempty"`
	Visibility  string   `json:"visibility,omitempty"`
	AccessKey   string   `json:"access_key,omitempty"`
	Checks      []string `json:"checks,omitempty"`
}

StatusPage represents a status page

type StatusPageItem 

type StatusPageItem struct {
	// List of checks to show in the page (array of check tokens, order is respected)
	Checks []string `json:"checks,omitempty"`
	// Name of the status page
	Name string `json:"name,omitempty"`
	// Description text (displayed below the name, supports newlines and links)
	Description string `json:"description,omitempty"`
	// Page visibility: 'public', 'protected', or 'private'
	Visibility string `json:"visibility,omitempty"`
	// Access key for protected pages
	AccessKey string `json:"access_key,omitempty"`
}

StatusPageItem represents a status page to create or update

type StatusPageService 

type StatusPageService struct {
	// contains filtered or unexported fields
}

StatusPageService interacts with the status pages section of the API

func (*StatusPageService) Add 

func (s *StatusPageService) Add(data StatusPageItem) (StatusPage, *http.Response, error)

Add creates a new status page

func (*StatusPageService) Get 

func (s *StatusPageService) Get(token string) (StatusPage, *http.Response, error)

Get gets a single status page by its token from the list

func (*StatusPageService) List 

func (s *StatusPageService) List() ([]StatusPage, *http.Response, error)

List lists all status pages

func (*StatusPageService) Remove 

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

Remove removes a status page by its token

func (*StatusPageService) Update 

func (s *StatusPageService) Update(token string, data StatusPageItem) (StatusPage, *http.Response, error)

Update updates a status page

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.