incident_io

An Elixir client for the incident.io API.

With just a few lines of code you can begin interacting:

Mix.install([
  {:incident_io, "~> 0.3.0"}
])

client = IncidentIo.Client.new(%{api_key: System.fetch_env!("INCIDENT_API_KEY")})
IncidentIo.IncidentsV2.create(client,
                              idempotency_key: "your-idempotency-key",
                              visibility: :public)

Requirements

You'll need an incident.io account to use this package. Sign up on their website if you don't already have one.

Installation

Add :incident_io to the dependencies in your project's mix.exs:

def deps do
  [
    {:incident_io, "~> 0.1"}
  ]
end

Getting started

You will need to create an API key via your incident.io dashboard to make requests. Please note their warning message about the scope for this API key:

When you create the key, you'll be able to choose what actions it can take for your account: choose carefully, as those roles can only be set when you first create the key.

Once you've created an API key then you're ready to start making requests.

Example

Assuming that you've created and configured your incident.io API key as an environment variable named INCIDENT_API_KEY, you can create and read incidents as simply as the following example module:

defmodule MyIncidentIo do
  use IncidentIo

  alias IncidentIo.Client
  alias IncidentIo.IncidentsV2

  def create(idempotency_key)
    IncidentsV2.create(client, idempotency_key: idempotency_key, visibility: :public)
  end

  def read(incident_id)
    IncidentsV2.show(client, incident_id)
  end

  defp client
    Client.new(%{api_key: System.fetch_env!("INCIDENT_API_KEY")})
  end
end

Pagination

Many list endpoints return results in pages. The response includes a pagination_meta.after cursor that you pass as the :after option to fetch the next page.

IncidentIo.Pagination.stream/3 handles this for you. It wraps any 2-arity list function and returns a lazy Stream of page bodies, advancing through pages automatically until the cursor is nil:

client = IncidentIo.Client.new(%{api_key: System.fetch_env!("INCIDENT_API_KEY")})

# Collect every incident across all pages
all_incidents =
  IncidentIo.Pagination.stream(&IncidentIo.IncidentsV2.list/2, client)
  |> Enum.flat_map(fn %{incidents: incidents} -> incidents end)

# Process pages lazily without loading them all into memory
IncidentIo.Pagination.stream(&IncidentIo.SchedulesV2.list/2, client)
|> Stream.each(fn %{schedules: page} -> process(page) end)
|> Stream.run()

# Pass extra options (e.g. page_size) — :after is managed automatically
IncidentIo.Pagination.stream(&IncidentIo.IncidentsV2.list/2, client, page_size: 50)
|> Enum.flat_map(fn %{incidents: incidents} -> incidents end)

If a page returns a non-200 status code the stream stops and that page is not emitted. Call the underlying function directly if you need to inspect the error body.

Development

Requirements

• Elixir (see .tool-versions or mix.exs for version)
• Homebrew (for installing pre-commit hook dependencies)

Setup

To start working on this application, clone the repository and fetch its dependencies:

git clone https://github.com/sgerrand/ex_incident_io.git
cd ex_incident_io
mix deps.get
bin/setup

Then you can start running the tests.

mix test

bin/setup installs the pre-commit hook tools (actionlint, check-jsonschema, lefthook, markdownlint-cli2) and activates the hooks. mix setup fetches Elixir dependencies.

Common commands

mix test          # Run tests
mix credo         # Lint
mix format        # Format code
mix coveralls     # Test coverage

Contributing

Bug reports and pull requests are welcomed.

License

This package is available as open source under the terms of the MIT License.