pdrc is an API wrapper for Pagerduty's REST API v2, based off amro's great MailChimp client Gibbon.
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
.
$ gem install pdrc
A Pagerduty account and a v2 API key. Only administrators can generate API keys.
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.
Pass debug: true
to enable debug logging to STDOUT.
pdrc = PDRC::Request.new(api_key: "your_api_key", debug: true)
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
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
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"})
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
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 to everyone who has contributed to Gibbon's development which has been so integral to PDRC's development.
- Copyright (c) 2010-2018 Amro Mousa & Lucas Willett. See LICENSE.txt for details.