Class: Snitcher::API::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/snitcher/api/client.rb

Constant Summary collapse

DEFAULT_ENDPOINT = 
"https://api.deadmanssnitch.com"

Instance Method Summary collapse

Constructor Details

#initialize(key, options = {}) ⇒ Snitcher::API::Client

Create a new API Client for taling to Dead Man’s Snitch’s API.

Examples:

Creating a new Client with an API key

client = Snitcher::API::Client.new("abc123")
# => #<Snitcher::API::Client...>

Parameters:

  • key (String) —

    API access key (available at deadmanssnitch.com/account/keys).

  • options (Hash) (defaults to: {}) —

    advanced options for customizing the client

Options Hash (options):

  • :endpoint (String) —

    URL of the DMS API to connect to

  • :timeout (Float, Fixnum) —

    number of seconds to wait at most for a response from the API.



31
32
33
34
35
36
37
 
# File 'lib/snitcher/api/client.rb', line 31

def initialize(key, options = {})
  endpoint = options[:endpoint] || DEFAULT_ENDPOINT

  @key      = key
  @endpoint = URI.parse(endpoint).freeze
  @timeout  = options.fetch(:timeout, 5.0)
end

Instance Method Details

#add_tags(token, tags = []) ⇒ Array<String>

Add one or more tags to an existing snitch, identified by token.

Examples:

Add tags to an existing snitch.

client.add_tags("c2354d53d2", ["red", "green"])
# => [ "yellow", "red", "green" ]

Adding a single tag

client.add_tags("c2354d53d2", "orange")
# => [ "yellow", "orange" ]

Parameters:

  • token (String) —

    The unique token of the Snitch.

  • tags (Array<String>) (defaults to: []) —

    Tag or tags to add to the list of tags already on the Snitch.

Returns:

  • (Array<String>) —

    full list of tags on the Snitch.

Raises:



218
219
220
221
222
 
# File 'lib/snitcher/api/client.rb', line 218

def add_tags(token, tags = [])
  token = CGI.escape(token)

  post("/v1/snitches/#{token}/tags", Array(tags).flatten)
end

#create_snitch(attributes = {}) ⇒ Snitcher::API::Snitch

Create a new Snitch.

Examples:

Create a new Snitch

client.create_snitch({
  name:  "Daily Backups",
  interval: "hourly",
  notes: "On error check the print tray for paper jams",
  tags:  [ "backups", "maintenance" ],
})

# => #<Snitcher::API::Snitch:...>

Parameters:

  • attributes (Hash) (defaults to: {}) —

    The properties for the new Snitch

Options Hash (attributes):

  • :name (String) —

    The label used for the Snitch

  • :interval (String) —

    How often the snitch is expected to check-in. One of: “15_minute”, “30_minute”, “hourly”, “daily”, “weekly”, or “monthly”.

  • :notes (optional, String) —

    Additional information about the Snitch. Useful to put instructions of investigating or fixing any errors.

  • :tags (optional, Array<String>) —

    List of labels to tag the Snitch with.

Returns:

Raises:



134
135
136
137
138
139
140
141
142
 
# File 'lib/snitcher/api/client.rb', line 134

def create_snitch(attributes = {})
  if interval = attributes.delete(:interval)
    type = attributes[:type] ||= {}
    type[:interval] ||= interval
  end

  response = post("/v1/snitches", attributes)
  Snitcher::API::Snitch.new(response)
end

#delete_snitch(token) ⇒ nil

Deletes a Snitch.

Examples:

Delete a Snitch.

client.delete_snitch("c2354d53d2")
# => { :message => "Response complete" }

Parameters:

  • token (String) —

    The unique token of the Snitch to delete.

Returns:

  • (nil)

Raises:



280
281
282
283
284
285
286
 
# File 'lib/snitcher/api/client.rb', line 280

def delete_snitch(token)
  token = CGI.escape(token)

  delete("/v1/snitches/#{token}")

  nil
end

#pause_snitch(token) ⇒ nil

Pauses a Snitch if it can be paused. Snitches can only be paused if their status is currently “failing” or “errored”.

Examples:

Pause a Snitch

client.pause_snitch("c2354d53d2")
# => true

Parameters:

  • token (String) —

    The unique token of the Snitch.

Returns:

  • (nil)

Raises:



259
260
261
262
263
264
265
 
# File 'lib/snitcher/api/client.rb', line 259

def pause_snitch(token)
  token = CGI.escape(token)

  post("/v1/snitches/#{token}/pause")

  nil
end

#remove_tag(token, tag) ⇒ Array<String>

Remove a tag from a Snitch.

Examples:

Removing the “production” tag from a Snitch

client.remove_tag("c2354d53d2", "production")
# => [ "critical" ]

Parameters:

  • token (String) —

    The unique token of the Snitch.

  • tag (String) —

    The tag to remove from the Snitch.

Returns:

  • (Array<String>) —

    list of the remaining tags on the Snitch.

Raises:



238
239
240
241
242
243
 
# File 'lib/snitcher/api/client.rb', line 238

def remove_tag(token, tag)
  token = CGI.escape(token)
  tag = CGI.escape(tag)

  delete("/v1/snitches/#{token}/tags/#{tag}")
end

#snitch(token) ⇒ Snitcher::API::Snitch

Get a single Snitch by it’s unique token.

Examples:

Get the Snitch with token “c2354d53d2”

client.snitch("c2354d53d2")

# => #<Snitcher::API:: @token="c2354d53d2" ...>

Parameters:

  • token (String) —

    The unique token of the Snitch to get

Returns:

Raises:



98
99
100
101
102
103
 
# File 'lib/snitcher/api/client.rb', line 98

def snitch(token)
  token = CGI.escape(token)

  payload = get("/v1/snitches/#{token}")
  Snitcher::API::Snitch.new(payload)
end

#snitches(filters = {}) ⇒ Array<Snitcher::API::Snitch>

Get the list snitches on the account

Examples:

List the Snitches on an account

client.snitches
# => [ #<Snitcher::API::Snitch:...>, #<Snitcher::API::Snitch:...> ]

List Snitches with a specific tag

client.snitches(tags: "production")
# => [ #<Snitcher::API::Snitch:...>, #<Snitcher::API::Snitch:...> ]

List Snitches with multiple tags

client.snitches(tags: ["production", "critical"])
# => [ #<Snitcher::API::Snitch:...>, #<Snitcher::API::Snitch:...> ]

Parameters:

  • filters (Hash) (defaults to: {})

Options Hash (filters):

  • tags (String, Array<String>) —

    only return Snitches that are tagged with all of the given tags. For example, if a Snitch is tagged with “production” and “critical” it will be returned when filtering by “production”, “critical”, or [“production”, “critical”] but not [“production”, “backups”].

Returns:

Raises:

  • (Timeout::Error) —

    if the API request took too long to execute.

  • (Snitcher::API::Error) —

    if any API errors occur.



64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/snitcher/api/client.rb', line 64

def snitches(filters = {})
  query = {}

  # Tags allow for labeling Snitches for better categorization. This allows
  # filtering by a set of tags.
  if tags = filters[:tags]
    tags = Array(tags).flatten
    query[:tags] = tags.map(&:strip).compact.uniq.join(",")
  end

  # JSON array of Snitch attributes
  response = get("/v1/snitches", query)

  # Convert the attributes hashes into Objects
  response.map! do |snitch|
    Snitcher::API::Snitch.new(snitch)
  end
end

#update_snitch(token, attributes = {}) ⇒ Object

Update a snitch, identified by token, using passed-in values. Only changes those values included in the attributes hash; other attributes are not changed.

Raise Timeout::Error if the API request times out

Examples:

Update an existing Snitch

client.update_snitch("c2354d53d2", {
  name: "Monthly Backups",
})
# => #<Snitcher::API::Snitch:...>

Setting Tags for a Snitch

client.update_snitch("c2354d53d2", tags: ["production", "backup"])
# => #<Snitcher::API::Snitch: @tags=["production", "backup"])

Removing Tags from a Snitch

client.update_snitch("c2354d53d2", tags: [])
or
client.update_snitch("c2354d53d2", tags: nil)

Parameters:

  • token (String) —

    The unique token of the Snitch.

  • attributes (Hash) (defaults to: {}) —

    the set of Snitch attributes to change.

Options Hash (attributes):

  • :name (String) —

    The label used for the Snitch

  • :interval (String) —

    How often the snitch is expected to check-in. One of: “15_minute”, “30_minute”, “hourly”, “daily”, “weekly”, or “monthly”.

  • :notes (optional, String) —

    Additional information about the Snitch. Useful to put instructions of investigating or fixing any errors.

  • :tags (optional, Array<String>, nil) —

    List of labels to tag the Snitch with.

Raises:



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/snitcher/api/client.rb', line 182

def update_snitch(token, attributes = {})
  if attributes.key?(:tags)
    attributes[:tags] = [attributes[:tags]].flatten.compact
  end

  # Expand the interval key to the full structure required by the API
  if interval = attributes.delete(:interval)
    type = attributes[:type] ||= {}
    type[:interval] ||= interval
  end

  token = CGI.escape(token)
  payload = patch("/v1/snitches/#{token}", attributes)

  Snitcher::API::Snitch.new(payload)
end