pdrc

pdrc is an API wrapper for Pagerduty's REST API v2, based off amro's great MailChimp client Gibbon.

Important Notes

Please read Pagerduty's Overview documentation.

pdrc returns a PDRC::Response instead of the response body directly. PDRC::Response exposes the parsed response body and headers.

Installation

$ gem install pdrc

Requirements

A Pagerduty account and a v2 API key. Only administrators can generate API keys.

Usage

First, create a one-time use instance of PDRC::Request:

pdrc = PDRC::Request.new(api_key: "your_api_key")

Note Only reuse instances of pdrc after terminating a call with a verb, which makes a request. Requests are light weight objects that update an internal path based on your call chain. When you terminate a call chain with a verb, a request instance makes a request and resets the path.

You can set an individual request's timeout and open_timeout like this:

pdrc.timeout = 30
pdrc.open_timeout = 30

You can read about timeout and open_timeout in the Net::HTTP doc.

Now you can make requests using the resources defined in Pagerduty's docs. Resource IDs are specified inline and a CRUD (create, retrieve, update, or delete) verb initiates the request.

You can specify headers, params, and body when calling a CRUD method. For example:

pdrc.teams.retrieve(headers: {"SomeHeader": "SomeHeaderValue"}, params: {"query_param": "query_param_value"})

Of course, body is only supported on create and update calls. Those map to HTTP POST, PATCH, and PUT verbs respectively.

You can set api_key, timeout, open_timeout, faraday_adapter, proxy, symbolize_keys, logger, and debug globally:

PDRC::Request.api_key = "your_api_key"
PDRC::Request.timeout = 15
PDRC::Request.open_timeout = 15
PDRC::Request.symbolize_keys = true
PDRC::Request.debug = false

For example, you could set the values above in an initializer file in your Rails app (e.g. your_app/config/initializers/pdrc.rb).

Assuming you've set an api_key on PDRC, you can conveniently make API calls on the class itself:

PDRC::Request.teams.retrieve

You can also set the environment variable PAGERDUTY_API_KEY and PDRC will use it when you create an instance:

pdrc = PDRC::Request.new

Note Substitute an underscore if a resource name contains a hyphen.

Pass symbolize_keys: true to use symbols (instead of strings) as hash keys in API responses.

pdrc = PDRC::Request.new(api_key: "your_api_key", symbolize_keys: true)

Pagerduty's REST API documentation is a list of available resources.

Debug Logging

Pass debug: true to enable debug logging to STDOUT.

pdrc = PDRC::Request.new(api_key: "your_api_key", debug: true)

Custom logger

Ruby Logger.new is used by default, but it can be overrided using:

pdrc = PDRC::Request.new(api_key: "your_api_key", debug: true, logger: MyLogger.new)

Logger can be also set by globally:

PDRC::Request.logger = MyLogger.new

Examples

Teams

Fetch all teams:

pdrc.teams.retrieve

Retrieving a specific team looks like:

pdrc.teams(team_id).retrieve

Create a team:

pdrc.teams.create(body: {team: { type: "team", name: "Engineering", description: "The engineering team"}})

You can also delete a team:

pdrc.teams(team_id).delete

Schedules

Get all schedules:

pdrc.schedules.retrieve(params: {"query": "Primary"})

By default the Pagerduty API returns 25 results. To set the count to 50 (Note: it cannot exceed 100):

pdrc.schedules.retrieve(params: {"limit": "50"})

And to retrieve the next 50 schedules:

pdrc.schedules.retrieve(params: {"limit": "50", "offset": "50"})

And to retrieve only the schedules with the title containing "Primary":

pdrc.schedules.retrieve(params: {"limit": "50", "offset": "50", "query": "Primary"})

Get a list of overrides for a schedule:

pdrc.schedules(schedule_id).overrides.retrieve

Or to list users on-call for a schedule:

pdrc.schedules(schedule_id).users.retrieve

To narrow the range of on-call users down to a specific date range:

pdrc.schedules(schedule_id).users.retrieve(params: {"since": "2018-06-01T00:00:00Z", "until": "2018-09-01T00:00:00Z"})

Error handling

PDRC raises an error when the API returns an error.

PDRC::PagerdutyError has the following attributes: title, detail, body, raw_body, status_code. Some or all of these may not be available depending on the nature of the error. For example:

begin
  pdrc.teams(team_id).create(body: body)
rescue PDRC::PagerdutyError => e
  puts "Houston, we have a problem: #{e.message} - #{e.raw_body}"
end

Other

You can set an optional proxy url like this (or with an environment variable MAILCHIMP_PROXY):

pdrc.proxy = 'http://your_proxy.com:80'

You can set a different Faraday adapter during initialization:

pdrc = PDRC::Request.new(api_key: "your_api_key", faraday_adapter: :net_http)

Thanks

Thanks to everyone who has contributed to Gibbon's development which has been so integral to PDRC's development.

ltw/pdrc