{"id":16948153,"url":"https://github.com/technicalpickles/pager_duty-connection","last_synced_at":"2025-05-16T09:05:50.772Z","repository":{"id":7438529,"uuid":"8778265","full_name":"technicalpickles/pager_duty-connection","owner":"technicalpickles","description":"Ruby API wrapper for the PagerDuty REST API","archived":false,"fork":false,"pushed_at":"2025-02-25T14:38:35.000Z","size":87,"stargazers_count":31,"open_issues_count":2,"forks_count":48,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-13T19:00:02.835Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/technicalpickles.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-03-14T15:20:32.000Z","updated_at":"2025-02-27T02:36:06.000Z","dependencies_parsed_at":"2024-01-16T21:55:06.415Z","dependency_job_id":"5192d9ad-1721-451c-b2c8-a4eaa4a782d6","html_url":"https://github.com/technicalpickles/pager_duty-connection","commit_stats":{"total_commits":59,"total_committers":24,"mean_commits":"2.4583333333333335","dds":0.7627118644067796,"last_synced_commit":"ce973fe4de3ae0f403b218e21bad86daee72df35"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fpager_duty-connection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fpager_duty-connection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fpager_duty-connection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/technicalpickles%2Fpager_duty-connection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/technicalpickles","download_url":"https://codeload.github.com/technicalpickles/pager_duty-connection/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501557,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T21:49:46.909Z","updated_at":"2025-05-16T09:05:45.763Z","avatar_url":"https://github.com/technicalpickles.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PagerDuty::Connection\n\nPagerDuty::Connection is a Ruby wrapper for the [PagerDuty REST API](http://developer.pagerduty.com/documentation/rest)\n\nIt has a few design goals:\n\n* be usable to someone familiar with Ruby\n* be usable to someone familiar with the PagerDuty REST API, or at least able to read the documentation\n* try to be future proof for API additions\n* try not to do too much magic, in order to support the above\n\nIn the end, this is what it does:\n\n* 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\n* provide a simpler way to do pagination (pass `:page =\u003e ` to `get`), because using `limit` and `offset` using as [described by the API](http://developer.pagerduty.com/documentation/rest/pagination) is tedious in practice\n* converts time-like strings in responses to `Time` objects, since that is what most people will do anyways\n* 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`)\n* detect 404 errors, and raise them as `PagerDuty::Connection::FileNotFoundError` errors\n* detect [API errors](http://developer.pagerduty.com/documentation/rest/errors) and raise them as `PagerDuty::Connection::ApiError`\n\nAnd this is what it doesn't do:\n\n* provide first class objects for Incidents, Services, etc (they can change, and have new methods)\n* provide an a ActiveResource interface (ActiveResource libraries can be hard to build wrappers for. Also, it's not conducive to accessing multiple pagerduty accounts)\n* have methods for individual API calls that are possible (ie `find_incident`, `list_users`, etc)\n* 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)\n\n**Note**: v1 of the Pager Duty REST API is no longer supported with this gem. Please either upgrade to v2 of the API [(v2 Migration Documentation)](https://v2.developer.pagerduty.com/docs/migrating-to-api-v2) or do not upgrade past version [0.2.0 of this gem](https://github.com/technicalpickles/pager_duty-connection/tree/v0.2.0).\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"pager_duty-connection\"\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install pager_duty-connection\n\n## Usage\n\n\nWorking code is worth a thousand words. The basics:\n\n```ruby\n# setup the connection with API token\npagerduty = PagerDuty::Connection.new(token)\n\n# setup the connection with OAuth2 token\npagerduty = PagerDuty::Connection.new(token, token_type: :Bearer)\n\n# setup to use a custom domain\npagerduty = PagerDuty::Connection.new(token, token_type: :Bearer, url: \"https://custom.domain.com\")\n\n# 4 main methods: `get`, `post`, `put`, and `delete`:\n\nresponse = pagerduty.get(\"some/relative/path\", params)\nresponse = pagerduty.post(\"some/relative/path\", params)\nresponse = pagerduty.delete(\"some/relative/path\", params)\nresponse = pagerduty.put(\"some/relative/path\", params)\n\n# use something like irb or pry to poke around the responses\n# the contents will vary a bit between call, ie:\n\nresponse = pagerduty.get(\"incidents\")\nresponse.incidents # an array of incidents\n\nresponse = pagerduty.get(\"incidents/YYZ\")\nresponse # the hash/object that represents the array\n```\n\n`get`, `post`, `put`, and `delete` all take a common parameter `params`.\nThis parameter contains the query parameters, body, and custom headers\nneeded to perform the request. Params is structured as follows:\n\n```ruby\nparams = {\n  query_params: {\n    param1: \"ABCD\",\n    ids: [ \"id1\", \"id2\", \"id3\" ] # Faraday takes care of encoding the arrays to be `?ids[]=id1\u0026ids[]=id2\u0026ids[]=id3..`\n  }, {\n    body: { ... }, # Whatever needs to be sent in a `PUT` or `POST` request body\n  }, {\n    headers: {\n      from: \"testuser@test.com\" # Some requests require a From header\n    }\n  }\n}\n```\n\nFor more advanced and realistic examples, check out the examples directory:\n\n* [shifts-with-incidents-and-log-entries](examples/shifts-with-incidents-and-log-entries.rb)\n* [find-users](examples/find-users.rb)\n\nIn 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\n\nIf you are working in Rails, and using only a single PagerDuty account, you'll probably want an initializer:\n\n```ruby\n$pagerduty = PagerDuty::Connection.new(\"your-token\")\n```\n\nAnd if you are using [dotenv](https://github.com/bkeepers/dotenv), you can use environment variables, and stash them in .env:\n\n```ruby\naccount = ENV[\"PAGERDUTY_ACCOUNT\"] || raise(\"Missing ENV['PAGERDUTY_ACCOUNT'], add to .env\")\ntoken = ENV[\"PAGERDUTY_TOKEN\"] || raise(\"Missing ENV['PAGERDUTY_TOKEN'], add to .env.#{Rails.env}\")\n$pagerduty = PagerDuty::Connection.new(account, token)\n```\n\n## Questions and Answers\n\n\u003e What about the [pagerduty](https://github.com/envato/pagerduty) gem?\n\nThat is only for PagerDuty's [Integration API](http://developer.pagerduty.com/documentation/integration/events), ie for triggering/acknowleding/resolinv incidents\n\n\u003e What about the [pagerduty-full](https://github.com/gphat/pagerduty-full) gem?\n\nIt tries to be too clever and tightly models the API. For example, by having only Incident \u0026 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.\n\n\u003e What about [pagerduty_tools](https://github.com/precipice/pagerduty_tools)\n\nThat 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.\n\n\u003e Why not name it pagerduty-rest?\n\nThat would suggest a constant like Pagerduty::Rest, which I didn't like\n\n\u003e Why not name it pagerduty-connection?\n\nThat would suggest a constant like Pagerduty::Connection, where the company is called PagerDuty.\n\n\u003e Why the 'connection' thing?\n\nIt's an homage to [faraday](https://github.com/lostisland/faraday), which this library uses.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnicalpickles%2Fpager_duty-connection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftechnicalpickles%2Fpager_duty-connection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftechnicalpickles%2Fpager_duty-connection/lists"}