incidentio

v0.3.0

Published

2 months ago

<div align="center"> <img src="https://github.com/user-attachments/assets/b643774e-4edd-4312-adda-1d75d0c36661" width="200"> <p>On-call, incident response and status pages all under one roof.</p> <a href="https://api-docs.incident.io/"><img

Downloads

0High
0Medium
0Low

simplesagar

[!NOTE]
Please note this SDK has not been tested and is not yet for production use. It is primarily to showcase Speakeasy's generation capabilities using the Incident.io OpenAPI specification

Summary

incident.io: This is the API reference for incident.io.

It documents available API endpoints, provides examples of how to use it, and instructions around things like authentication and error handling.

The API is hosted at:

https://api.incident.io/

And you will need to create an API key via your incident.io dashboard to make requests.

Making requests

Here are the key concepts required to make requests to the incident.io API.

Authentication

For all requests made to the incident.io API, you'll need an API key.

To create an API key, head to the incident dashboard and visit API keys. 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. We'll only show you the token once, so make sure you store it somewhere safe.

Once you have the key, you should make requests to the API that set the Authorization request header using a "Bearer" authentication scheme:

Authorization: Bearer <YOUR_API_KEY>

Errors

We use standard HTTP response codes to indicate the status or failure of API requests.

The API response body will be JSON, and contain more detailed information on the nature of the error.

An example error when a request is made without an API key:

{
  "type": "authentication_error",
  "status": 401,
  "request_id": "8e3cc412-b49d-4957-9073-2c19d2c61804",
  "errors": [
    {
      "code": "missing_authorization_material",
      "message": "No authorization material provided in request"
    }
  ]
}

Note that the error:

Contains the HTTP status (401)
References the type of error (authentication_error)
Includes a request_id that can be provided to incident.io support to help debug questions with your API request
Provides a list of individual errors, which go into detail about why the error occurred

The most common error will be a 422 Validation Error, which is returned when the request was rejected due to failing validations.

These errors look like this:

{
  "type": "validation_error",
  "status": 422,
  "request_id": "631766c4-4afd-4803-997c-cd700928fa4b",
  "errors": [
    {
      "code": "is_required",
      "message": "A severity is required to open an incident",
      "source": {
        "field": "severity_id"
      }
    }
  ]
}

This error is caused by not providing a severity identifier, which should be at the severity_id field of the request payload. Errors like these can be mapped to forms, should you be integrating with the API from a user-interface.

Compatibility

We won't make breaking changes to existing API services or endpoints, but will expect integrators to upgrade themselves to the latest API endpoints within 3 months of us deprecating the old service.

We will make changes that are considered backwards compatible, which include:

Adding new API endpoints and services
Adding new properties to responses from existing API endpoints
Reordering properties returned from existing API endpoints
Adding optional request parameters to existing API endpoints
Altering the format or length of IDs
Adding new values to enums

It is important that clients are robust to these changes, to ensure reliable integrations.

As an example, if you are generating a client using an openapi-generator, ensure the generated client is configured to support unknown enum values, often configured via the enumUnknownDefaultCase parameter.

When breaking changes are unavoidable, we'll create a new service version on a separate path, and run them in parallel.

For example:

https://api.incident.io/v1/incidents
https://api.incident.io/v2/incidents

For any questions, email [email protected].

SDK Installation

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add incidentio

PNPM

pnpm add incidentio

Bun

bun add incidentio

Yarn

yarn add incidentio zod

# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

SDK Example Usage

Example

import { Incidentio } from "incidentio";

const incidentio = new Incidentio();

async function run() {
  const result = await incidentio.actions.list({
    incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
    isFollowUp: true,
    incidentMode: "real",
  });

  // Handle the result
  console.log(result);
}

run();

Available Resources and Operations

actions

~~list~~ - List Actions V1 :warning: Deprecated
~~get~~ - Show Actions V1 :warning: Deprecated

actionsV2

list - List Actions V2
get - Show Actions V2

alertEvents

createHTTP - CreateHTTP Alert Events V2

alertRoutes

create - Create Alert Routes V2
delete - Destroy Alert Routes V2
show - Show Alert Routes V2
update - Update Alert Routes V2

catalogEntries

list - ListEntries Catalog V2
create - CreateEntry Catalog V2
delete - DestroyEntry Catalog V2
show - ShowEntry Catalog V2
update - UpdateEntry Catalog V2

catalogResources

list - ListResources Catalog V2

catalogTypes

list - ListTypes Catalog V2
create - CreateType Catalog V2
delete - DestroyType Catalog V2
show - ShowType Catalog V2
update - UpdateType Catalog V2
updateSchema - UpdateTypeSchema Catalog V2

customFieldOptions

list - List Custom Field Options V1
create - Create Custom Field Options V1
delete - Delete Custom Field Options V1
get - Show Custom Field Options V1
update - Update Custom Field Options V1

customFields

create - Create Custom Fields V2
delete - Delete Custom Fields V2
get - Show Custom Fields V2
update - Update Custom Fields V2

customFieldsV2

list - List Custom Fields V2

escalationPaths

create - CreatePath Escalations V2
delete - DestroyPath Escalations V2
get - ShowPath Escalations V2
update - UpdatePath Escalations V2

followUps

list - List Follow-ups V2
get - Show Follow-ups V2

incidentAttachments

list - List Incident Attachments V1
create - Create Incident Attachments V1
delete - Delete Incident Attachments V1

incidentMemberships

create - Create Incident Memberships V1
revoke - Revoke Incident Memberships V1

incidentRoles

list - List Incident Roles V2
create - Create Incident Roles V2
delete - Delete Incident Roles V2
get - Show Incident Roles V2
update - Update Incident Roles V2

incidents

list - List Incidents V2
create - Create Incidents V2
get - Show Incidents V2
update - Edit Incidents V2

incidentStatuses

list - List Incident Statuses V1
create - Create Incident Statuses V1
delete - Delete Incident Statuses V1
get - Show Incident Statuses V1
update - Update Incident Statuses V1

incidentsV1

~~list~~ - List Incidents V1 :warning: Deprecated
~~create~~ - Create Incidents V1 :warning: Deprecated
~~get~~ - Show Incidents V1 :warning: Deprecated

incidentTimestamps

list - List Incident Timestamps V2
get - Show Incident Timestamps V2

incidentTypes

list - List Incident Types V1
get - Show Incident Types V1

incidentUpdates

list - List Incident Updates V2

scheduleEntries

list - ListScheduleEntries Schedules V2

schedules

list - List Schedules V2
create - Create Schedules V2
delete - Destroy Schedules V2
get - Show Schedules V2
update - Update Schedules V2

severities

list - List Severities V1
create - Create Severities V1
delete - Delete Severities V1
get - Show Severities V1
update - Update Severities V1

users

list - List Users V2
get - Show Users V2

utilities

identity - Identity Utilities V1
getOpenAPI - OpenAPI Utilities V1
getOpenApiv3 - OpenAPIV3 Utilities V1

workflows

list - ListWorkflows Workflows V2
create - CreateWorkflow Workflows V2
delete - DestroyWorkflow Workflows V2
get - ShowWorkflow Workflows V2
update - UpdateWorkflow Workflows V2

Standalone functions

All the methods listed above are available as standalone functions. These functions are ideal for use in applications running in the browser, serverless runtimes or other environments where application bundle size is a primary concern. When using a bundler to build your application, all unused functionality will be either excluded from the final bundle or tree-shaken away.

To read more about standalone functions, check FUNCTIONS.md.

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

import { Incidentio } from "incidentio";

const incidentio = new Incidentio();

async function run() {
  const result = await incidentio.actions.list({
    incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
    isFollowUp: true,
    incidentMode: "real",
  }, {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  // Handle the result
  console.log(result);
}

run();

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

import { Incidentio } from "incidentio";

const incidentio = new Incidentio({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

async function run() {
  const result = await incidentio.actions.list({
    incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
    isFollowUp: true,
    incidentMode: "real",
  });

  // Handle the result
  console.log(result);
}

run();

Error Handling

All SDK methods return a response object or throw an error. If Error objects are specified in your OpenAPI Spec, the SDK will throw the appropriate Error type.

| Error Object | Status Code | Content Type | | --------------- | --------------- | --------------- | | errors.SDKError | 4xx-5xx | / |

Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The SDKValidationError that is thrown as a result will capture the raw value that failed validation in an attribute called rawValue. Additionally, a pretty() method is available on this error that can be used to log a nicely formatted string since validation errors can list many issues and the plain error string may be difficult read when debugging.

import { Incidentio } from "incidentio";
import { SDKValidationError } from "incidentio/models/errors";

const incidentio = new Incidentio();

async function run() {
  let result;
  try {
    result = await incidentio.actions.list({
      incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
      isFollowUp: true,
      incidentMode: "real",
    });

    // Handle the result
    console.log(result);
  } catch (err) {
    switch (true) {
      case (err instanceof SDKValidationError): {
        // Validation errors can be pretty-printed
        console.error(err.pretty());
        // Raw value may also be inspected
        console.error(err.rawValue);
        return;
      }
      default: {
        throw err;
      }
    }
  }
}

run();

Server Selection

Select Server by Index

You can override the default server globally by passing a server index to the serverIdx optional parameter when initializing the SDK client instance. The selected server will then be used as the default on the operations that use it. This table lists the indexes associated with the available servers:

| # | Server | Variables | | - | ------ | --------- | | 0 | https://api.incident.io | None |

import { Incidentio } from "incidentio";

const incidentio = new Incidentio({
  serverIdx: 0,
});

async function run() {
  const result = await incidentio.actions.list({
    incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
    isFollowUp: true,
    incidentMode: "real",
  });

  // Handle the result
  console.log(result);
}

run();

Override Server URL Per-Client

The default server can also be overridden globally by passing a URL to the serverURL optional parameter when initializing the SDK client instance. For example:

import { Incidentio } from "incidentio";

const incidentio = new Incidentio({
  serverURL: "https://api.incident.io",
});

async function run() {
  const result = await incidentio.actions.list({
    incidentId: "01FCNDV6P870EA6S7TK1DSYDG0",
    isFollowUp: true,
    incidentMode: "real",
  });

  // Handle the result
  console.log(result);
}

run();

Custom HTTP Client

The TypeScript SDK makes API calls using an HTTPClient that wraps the native Fetch API. This client is a thin wrapper around fetch and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The HTTPClient constructor takes an optional fetcher argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to use the "beforeRequest" hook to to add a custom header and a timeout to requests and how to use the "requestError" hook to log errors:

import { Incidentio } from "incidentio";
import { HTTPClient } from "incidentio/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  }
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Incidentio({ httpClient });

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass a logger that matches console's interface as an SDK option.

[!WARNING] Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.

import { Incidentio } from "incidentio";

const sdk = new Incidentio({ debugLogger: console });

Development

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.