pager_duty-connection 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+.env.development
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pager_duty-connection.gemspec
+gemspec
+
+# for tests & running examples
+group :development do
+  gem 'dotenv'
+  gem 'pry'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Josh Nichols
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,117 @@
+# PagerDuty::Connection
+
+PagerDuty::Connection is a Ruby wrapper for the [PagerDuty REST API](http://developer.pagerduty.com/documentation/rest)
+
+It has a few design goals:
+
+* be usable to someone familiar with Ruby
+* be usable to someone familiar with the PagerDuty REST API, or at least able to read the documentation
+* try to be future proof for API additions
+* try not to do too much magic, in order to support the above
+
+In the end, this is what it does:
+
+* provides methods for each of the HTTP methods you can use on the API, that takes a path (like if you copied from the documentation), and a Hash of request parameters to send
+* provide a simpler way to do pagination (pass `:page => ` to `get`), because using `limit` and `offset` using as [described by the API](http://developer.pagerduty.com/documentation/rest/pagination) is tedious in practice
+* converts time-like strings in responses to `Time` objects, since that is what most people will do anyways
+* converts time-like objects in requests to ISO 8601 strings, as this is documented as required by the API but is easy to forget and tedious to do anytime you use time parameters (ie `since` and `until`)
+* detect 404 errors, and raise them as `PagerDuty::Connection::FileNotFoundError` errors
+* detect [API errors](http://developer.pagerduty.com/documentation/rest/errors) and raise them as `PagerDuty::Connection::ApiError`
+
+And this is what it doesn't do:
+
+* provide first class objects for Incidents, Services, etc (they can change, and have new methods)
+* provide an a ActiveResource interface (ActiveResource libraries can be hard to built wrappers for. Also, it's not conducive to accessing multiple pagerduty accounts)
+* have methods for individual API calls that are possible (ie `find_incident`, `list_users`, etc)
+* provide [will_paginate](https://github.com/mislav/will_paginate) or [kaminari](https://github.com/amatsuda/kaminari) paginated arrays (They aren't super documented for building a library that works well with them, and have different APIs)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pager_duty-connection'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pager_duty-connection
+
+## Usage
+
+
+Working code is worth a thousand words. The basics:
+
+`` ruby
+# setup the connection
+pagerduty = PagerDuty::Connection.new(account, token)
+
+# 4 main methods: get, post, put, and delete:
+
+response = pagerduty.get('some/relative/path', :some => 'request', :parameter => 'to pass'
+response = pagerduty.post('some/relative/path', :some => 'request', :parameter => 'to pass'
+response = pagerduty.delete('some/relative/path', :some => 'request', :parameter => 'to pass'
+response = pagerduty.put('some/relative/path', :some => 'request', :parameter => 'to pass'
+
+# use something like irb or pry to poke around the responses
+# the contents will vary a bit between call, ie:
+
+response = pagerduty.get('incidents')
+response.incidents # an array of incidents
+
+response = pagerduty.get('incidents/YYZ')
+response # the hash/object that represents the array
+``
+
+For more advanced and realistic examples, check out the examples directory:
+
+* [shifts-with-incidents-and-log-entries](examples/shifts-with-incidents-and-log-entries.rb)
+* [find-users](examples/find-users.rb)
+
+In general, you can get/put/post/delete a path, with some attributes. Use the [REST API Documentation](http://developer.pagerduty.com/documentation/rest) to get some ideas
+
+If you are working in Rails, and using only a single PagerDuty account, you'll probably want an initializer:
+
+``ruby
+$pagerduty = PagerDuty::Connection.new('your-subdomain', 'your-token')
+``
+
+And if you are using [dotenv](https://github.com/bkeepers/dotenv), you can use environment variables, and stash them in .env:
+
+``ruby
+account = ENV['PAGERDUTY_ACCOUNT'] || raise("Missing ENV['PAGERDUTY_ACCOUNT'], add to .env")
+token = ENV['PAGERDUTY_TOKEN'] || raise("Missing ENV['PAGERDUTY_TOKEN'], add to .env.#{Rails.env}")
+$pagerduty = PagerDuty::Connection.new(account, token)
+``
+
+## Questions and Answers
+
+> What about the [pagerduty](https://github.com/envato/pagerduty) gem?
+
+That is only for PagerDuty's [Integration API](http://developer.pagerduty.com/documentation/integration/events), ie for triggering/acknowleding/resolinv incidents
+
+> What about the [pagerduty-full](https://github.com/gphat/pagerduty-full) gem?
+
+It tries to be too clever and tightly models the API. For exampe, by having only Incident & Schedule classes, with specific methods for doing specific API calls, it means having to update the gem anytime new resources are added, and new API methods.
+
+> What about [pagerduty_tools](https://github.com/precipice/pagerduty_tools)
+
+That gem is less about being an API, and more about tools for being on call. Also, it took months for [my pull request to be reviewed](https://github.com/precipice/pagerduty_tools/pull/6), so didn't give me a lot of hope for changes making it in.
+
+> Why not name it pagerduty-rest?
+
+That would suggest a constant like Pagerduty::Rest, which I didn't like
+
+> Why not name it pagerduty-connection?
+
+That would suggest a constant like Pagerduty::Connection
+
+## Contributing
+
+1. Fork it
+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 new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/examples/find-users.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require 'pry'
+require 'dotenv'
+Dotenv.load ".env.development", '.env'
+
+account = ENV['PAGERDUTY_ACCOUNT'] || raise("Missing ENV['PAGERDUTY_ACCOUNT'], add to .env.development")
+token = ENV['PAGERDUTY_TOKEN'] || raise("Missing ENV['PAGERDUTY_TOKEN'], add to .env.development")
+
+require 'pager_duty/connection'
+$pagerduty = PagerDuty::Connection.new(account, token)
+
+# http://developer.pagerduty.com/documentation/rest/users/list
+response = $pagerduty.get('users')
+response.users.each do |user|
+  puts "#{user.name}: #{user.email}"
+end

data/examples/shifts-with-incidents-and-log-entries.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+require 'dotenv'
+Dotenv.load ".env.development", '.env'
+
+account = ENV['PAGERDUTY_ACCOUNT'] || raise("Missing ENV['PAGERDUTY_ACCOUNT'], add to .env.development")
+token = ENV['PAGERDUTY_TOKEN'] || raise("Missing ENV['PAGERDUTY_TOKEN'], add to .env.development")
+
+require 'pager_duty/connection'
+$pagerduty = PagerDuty::Connection.new(account, token)
+
+schedule_id = ENV['PAGERDUTY_SCHEDULE_ID'] || raise("Missing ENV['PAGERDUTY_SCHEDULE_ID'], add to .env.development")
+
+# pull down schedule entires for XXX schedule in the last day (ie who has been on call, and when
+time_since = 1.day.ago
+time_until = Time.now
+
+# http://developer.pagerduty.com/documentation/rest/schedules/entries
+response = $pagerduty.get("schedules/#{schedule_id}/entries", 'since' => time_since, 'until' => time_until, :overflow => true)
+
+entries = response['entries'] # note, probably a bug, but response.entries doesn't do what you think it does
+
+entries.each do |entry|
+  puts "#{entry.start} - #{entry.end}: #{entry.user.name}"
+
+  # find incidents during that shift
+  # http://developer.pagerduty.com/documentation/rest/incidents/list
+  response = $pagerduty.get('incidents', :since => entry['start'], :until => entry['end'])
+
+  response.incidents.each do |incident|
+    puts "\t#{incident.id}"
+
+    # find log entries (acknowledged, notifications, etc) for incident:
+    # http://developer.pagerduty.com/documentation/rest/log_entries/incident_log_entries
+    response = $pagerduty.get("incidents/#{incident.id}/log_entries")
+
+    # select just the notes
+    notes = response.log_entries.select do |log_entry|
+      log_entry.channel && log_entry.channel.type == 'note'
+    end
+
+    # and print them out:
+    notes.each do |log_entry|
+      puts "\t\t#{log_entry.channel.summary}"
+    end
+  end
+end

data/lib/pager_duty-connection.rb

@@ -0,0 +1,2 @@
+# convenience require for folks using bundler
+require "pager_duty/connection"

data/lib/pager_duty.rb

@@ -0,0 +1,6 @@
+require 'pager_duty/connection/version'
+
+module PagerDuty
+  autoload :Connection, 'pager_duty/connection'
+end
+

data/lib/pager_duty/connection.rb

@@ -0,0 +1,151 @@
+require 'faraday'
+require 'faraday_middleware'
+require 'active_support/core_ext'
+require 'active_support/time_with_zone'
+
+module PagerDuty
+
+  class Connection
+    attr_accessor :connection
+    attr_accessor :api_version
+
+    class FileNotFoundError < RuntimeError
+    end
+
+    class ApiError < RuntimeError
+    end
+
+    class RaiseFileNotFoundOn404 < Faraday::Middleware
+      def call(env)
+        response = @app.call env
+        if response.status == 404
+          raise FileNotFoundError, response.env[:url].to_s
+        else
+          response
+        end
+      end
+    end
+
+    class RaiseApiErrorOnNon200 < Faraday::Middleware
+      def call(env)
+        response = @app.call env
+        if response.status != 200
+          url = response.env[:url].to_s
+          if error = response.body['error']
+            # TODO May Need to check error.errors too
+            raise ApiError, "Got HTTP #{response.status} back for #{url}. Error code #{error.code}: #{error.message}"
+          else
+            raise ApiError, "Got HTTP #{response.status} back for #{url}"
+          end
+        else
+          response
+        end
+      end
+    end
+
+    class ConvertTimesParametersToISO8601  < Faraday::Middleware
+      TIME_KEYS = [:since, :until]
+      def call(env)
+
+        body = env[:body]
+        TIME_KEYS.each do |key|
+          if body.has_key?(key) 
+            body[key] = body[key].iso8601 if body[key].respond_to?(:iso8601)
+          end
+        end
+
+        response = @app.call env
+      end
+
+
+    end
+
+    class ParseTimeStrings < Faraday::Middleware
+      TIME_KEYS = %w(start end created_on last_status_change_on started_at created_at last_incident_timestamp)
+
+      OBJECT_KEYS = %w(override entry incident alert service)
+
+      def call(env)
+        response = @app.call env
+
+        OBJECT_KEYS.each do |key|
+          object = env[:body][key]
+          parse_object_times(object) if object
+          
+          collection_key = key.pluralize
+          collection = env[:body][collection_key]
+          parse_collection_times(collection) if collection
+        end
+
+        response
+      end
+
+      def parse_collection_times(collection)
+        collection.each do |object|
+          parse_object_times(object)
+        end
+      end
+
+      def parse_object_times(object)
+        time = Time.zone ? Time.zone : Time
+
+        TIME_KEYS.each do |key|
+          object[key] = time.parse(object[key]) if object.has_key?(key)
+        end
+      end
+    end
+
+    def initialize(account, token, api_version = 1)
+      @api_version = api_version
+      @connection = Faraday.new do |conn|
+        conn.url_prefix = "https://#{account}.pagerduty.com/api/v#{api_version}"
+
+        # use token authentication: http://developer.pagerduty.com/documentation/rest/authentication
+        conn.token_auth token
+
+
+        conn.use ParseTimeStrings
+        conn.use RaiseApiErrorOnNon200
+        # json back, mashify it
+        conn.response :mashify
+        conn.response :json, :content_type => /\bjson$/
+        conn.use RaiseFileNotFoundOn404
+
+        conn.use ConvertTimesParametersToISO8601 
+        # use json
+        conn.request :json
+
+        conn.adapter  Faraday.default_adapter
+      end
+    end
+
+    def get(path, options = {})
+      # paginate anything being 'get'ed, because the offset/limit isn't intutive
+      page = (options.delete(:page) || 1).to_i
+      limit = (options.delete(:limit) || 100).to_i
+      offset = (page - 1) * limit
+
+      run_request(:get, path, options.merge(:offset => offset, :limit => limit))
+    end
+
+    def put(path, options = {})
+      run_request(:put, path, options)
+    end
+
+    def post(path, options = {})
+      run_request(:put, path, options)
+    end
+
+    def delete(path, options = {})
+      run_request(:delete, path, options)
+    end
+
+    def run_request(method, path, options)
+      path = path.gsub(/^\//, '') # strip leading slash, to make sure relative things happen on the connection
+      headers = nil
+      response = connection.run_request(method, path, options, headers)
+      response.body
+    end
+
+  end
+end

data/lib/pager_duty/connection/version.rb

@@ -0,0 +1,5 @@
+module PagerDuty
+  class Connection
+    VERSION = "0.0.1"
+  end
+end

data/pager_duty-connection.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pager_duty/connection/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "pager_duty-connection"
+  gem.version       = PagerDuty::Connection::VERSION
+  gem.authors       = ["Josh Nichols"]
+  gem.email         = ["josh@technicalpickles.com"]
+  gem.description   = %q{Ruby API wrapper for the PagerDuty REST API}
+  gem.summary       = %q{Written with the power of faraday, pager_duty-connection tries to be a simple and usable Ruby API wrapper for the PagerDuty REST API}
+  gem.homepage      = "http://github.com/technicalpickles/pager_duty-connection"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_dependency "faraday", "~> 0.8.6"
+  gem.add_dependency "faraday_middleware", "~> 0.9.0"
+  gem.add_dependency "activesupport", "~> 3.2"
+  gem.add_dependency "hashie", "~> 1.2"
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: pager_duty-connection
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Josh Nichols
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.6
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: Ruby API wrapper for the PagerDuty REST API
+email:
+- josh@technicalpickles.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/find-users.rb
+- examples/shifts-with-incidents-and-log-entries.rb
+- lib/pager_duty-connection.rb
+- lib/pager_duty.rb
+- lib/pager_duty/connection.rb
+- lib/pager_duty/connection/version.rb
+- pager_duty-connection.gemspec
+homepage: http://github.com/technicalpickles/pager_duty-connection
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Written with the power of faraday, pager_duty-connection tries to be a simple
+  and usable Ruby API wrapper for the PagerDuty REST API
+test_files: []
+has_rdoc: