Events

Resource description

All endpoints adhere to the JSON API specification.

Attributes

Name

Description

Required?

Type

Notes

name

Display name for the Event

True

string

causeType

First Outage’s Cause is only Cause, or all Causes count

True

string

Default: "multi". Accepted values: "multi", "single"

saidi

SAIDI based on Event’s current Outages

False

float

Calculated read-only

saifi

SAIFI based on Event’s current Outages

False

float

Calculated read-only

daySaidi

SAIDI based on all Utility’s Events for the same day

False

float

Calculated read-only

startDatetime

Start date and time of earliest Outage for this Event

False

string

Calculated read-only, ISO 8601 formatted ex. 2014-02-04T16:20:00Z

Relationships

Name

Description

Required?

Type

utility

Utility this Event belongs to

True

Foreign key

List Events

A user must have at least “member” authorization to list Events for their Utility.

GET https://reliability.api.publicpower.org/v1/events/

Example request:

GET /v1/events/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken
Request Headers
Query Parameters

  • page (int) – Page Number of results to request.

  • page_size (int) – Number of results to return per-page.

  • filter[utility] (int) – Only return results for a given Utility ID.

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "first": "https://reliability.api.publicpower.dev/v1/events/?page=1",
    "last": "https://reliability.api.publicpower.dev/v1/events/?page=7182",
    "next": "https://reliability.api.publicpower.dev/v1/events/?page=3",
    "prev": "https://reliability.api.publicpower.dev/v1/events/?page=1"
  },
  "data": [
  {
    "type": "Event",
    "id": "404044",
    "attributes": {
      "name": "Great Alberta Clipper",
      "saidi": 0.00262326357837,
      "saifi": 0.000119239253562273,
      "daySaidi": 0.00262326357837,
      "startDatetime": "2008-09-26T23:09:00Z",
      "causeType": "multi"
    },
    "relationships": {
      "utility": {
        "data": {
          "type": "Utility",
          "id": "3"
        }
      }
    }
  }
  ],
  "meta": {
    "pagination": {
      "page": 2,
      "pages": 7182,
      "count": 7182
    }
  }
}
Status Codes

  • 200 OK – Successful response

  • 401 Unauthorized – You did not provide a valid Authorization: Bearer token.

  • 403 Forbidden – Your user role is not authorized to access this endpoint.

Create an Event

A user must have at least “member” authorization to create Events for their Utility.

POST https://reliability.api.publicpower.org/v1/events/

Example request:

POST /v1/events/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

{
  "data": {
    "attributes": {
      "name": "Great Alberta Clipper"
    },
    "type": "Event",
    "relationships": {
      "utility": {
        "data": {
          "type": "Utility",
          "id": "1"
        }
      }
    }
  }
}
Request Headers

Example response:

HTTP/1.1 201 Created
Vary: Accept
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "Event",
    "id": "267519",
    "attributes": {
      "name": "Great Alberta Clipper",
      "saidi": null,
      "saifi": null,
      "daySaidi": null,
      "startDatetime": null,
      "causeType": "multi"
    },
    "relationships": {
      "utility": {
        "data": {
          "type": "Utility",
          "id": "1"
        }
      }
    }
  }
}
Status Codes

Retrieve an Event

A user must have at least “member” authorization to retrieve Events for their Utility.

GET https://reliability.api.publicpower.org/v1/events/(int: event_id)/

Example request:

GET /v1/events/123/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken
Request Headers

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "Event",
    "id": "123",
    "attributes": {
      "name": "Great Alberta Clipper",
      "saidi": 0.00262326357837,
      "saifi": 0.000119239253562273,
      "daySaidi": 0.00262326357837,
      "startDatetime": "2008-09-26T23:09:00Z",
      "causeType": "multi"
    },
    "relationships": {
      "utility": {
        "data": {
          "type": "Utility",
          "id": "3"
        }
      }
    }
  }
}
Status Codes

  • 200 OK – Successful response

  • 401 Unauthorized – You did not provide a valid Authorization: Bearer token.

  • 403 Forbidden – Your user role is not authorized to access this endpoint.

Update an Event

A user must have at least “member” authorization to update Events for their Utility.

PATCH https://reliability.api.publicpower.org/v1/events/(int: event_id)/

Example request:

PATCH /v1/events/123/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

{
  "data": {
    "attributes": {
      "name": "Great Nor'Easter"
    },
    "type": "Event",
    "id": "123"
  }
}
Request Headers

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "Event",
    "id": "123",
    "attributes": {
      "name": "Great Nor'Easter",
      "saidi": 0.008442380751371888,
      "saifi": 0.0001407063458561981,
      "daySaidi": 0.008442380751371888,
      "startDatetime": "2012-04-13T22:00:00Z",
      "causeType": "multi"
    },
    "relationships": {
      "utility": {
        "data": {
          "type": "Utility",
          "id": "21"
        }
      }
    }
  }
}
Status Codes

Delete an Event

A user must have at least “member” authorization to delete Events for their Utility.

DELETE https://reliability.api.publicpower.org/v1/events/(int: event_id)/

Example request:

DELETE /v1/events/123/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken
Request Headers

Example response:

HTTP/1.1 204 No Content
Content-Type: application/vnd.api+json
Status Codes