Utilities¶

Table of Contents

Resource description
- Attributes
- Relationships
List Utilities
Create a Utility
Retrieve a Utility
Update a Utility
Delete a Utility

Resource description ¶

All endpoints adhere to the JSON API specification.

Attributes ¶

Utility Attributes¶
Name	Description	Required?	Type	Notes
address	Street address of the Utility	False	string
aptifyId	APPA Utility code	False	integer
aptifyOrderId	APPA Utility order	False	integer
averageAnnualHouseholdIncome	Average household income for residential meters serviced by Utility	False	decimal	2 decimals of precision, 12 digits allowed in total
averageAnnualMegawattHours	Average annual megawatt hour production by the Utility	False	decimal	9 decimals of precision, 15 digits allowed in total
city	City of the Utility	False	string
estIsActive	Utility’s users can use eST	True	bool
estSubscriptionId	Utility’s eST Subscription ID	False	integer	For Admins only it is required and must be in the range of 1-2147483647. Other users cannot view or edit this field. `Null` is allowed.
isActive	Utility’s users can use eRT	True	bool
name	Display name for the Utility	True	string
state	State code of the Utility	False	string
totalCustomers	Total customers servced by the Utility	True	integer
totalSubscriptions	Total number of Safety Manual Licenses for Utility	True	integer
milesOfLine	Total miles of line for the Utility	False	integer
lineLengthOverhead	Total miles of overhead line for the Utility	False	integer
lineLengthUnderground	Total miles of underground line for the Utility	False	integer
useMeters	Marks that Meter data is complete and should be used for reporting	False	bool
whenUpdate	Date and time the utlity was last modified	False	string	ISO 8601 formatted ex. 2014-02-04T16:20:00Z
zipCode	Zip code of the Utility	False	string

Relationships ¶

Name	Description	Required?	Type
members	Users that belong to this Utility	True	Foreign key

List Utilities ¶

A user must have “spectator” authorization to list Utilities.

GET https://reliability.api.publicpower.org/v1/utilities/¶

Example request:

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

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Query Parameters

page (int) – Page Number of results to request.
page_size (int) – Number of results to return per-page.
sort (string) – Comma separated attribute names used to sort list. Available options: estIsActive, name, isActive, and totalCustomers.
filter[aptify_id] (int) – Limit results to a single Aptify ID

Example response:

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

{
  "links": {
    "first": "https://reliability.api.publicpower.dev/v1/utilities/?page=1",
    "last": "https://reliability.api.publicpower.dev/v1/utilities/?page=1",
    "next": null,
    "prev": null
  },
  "data": [
    {
      "type": "Utility",
      "id": "160",
      "attributes": {
        "address": "1875 Connecticut Ave, NW, Suite 1200",
        "aptifyId": 1234,
        "aptifyOrderId": null,
        "averageAnnualHouseholdIncome": "0.00",
        "averageAnnualMegawattHours": "999999.999999999",
        "city": "Washington",
        "estIsActive": true,
        "estSubscriptionId": 1,
        "isActive": true,
        "name": "TESST APPA Utility",
        "state": "DC",
        "totalCustomers": 22500,
        "totalSubscriptions": 10,
        "milesOfLine": 1200,
        "lineLengthOverhead": 600,
        "lineLengthUnderground": 600,
        "useMeters": true,
        "whenUpdate": "2021-06-29T11:41:45.522312Z",
        "zipCode": "20009"
      },
      "relationships": {
        "members": {
          "data": [
            {
              "type": "User",
              "id": "2"
            }
          ],
          "meta": {
            "count": 1
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pages": 1,
      "count": 1
    }
  }
}

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 a Utility ¶

A user must have “admin” authorization to create Utilities.

POST https://reliability.api.publicpower.org/v1/utilities/¶

Example request:

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

{
  "data": {
    "type": "Utility",
    "attributes": {
      "address": "1875 Connecticut Ave, NW, Suite 1200",
      "aptifyId": 1234,
      "aptifyOrderId": null,
      "averageAnnualHouseholdIncome": "0.00",
      "averageAnnualMegawattHours": "999999.999999999",
      "city": "Washington",
      "estIsActive": true,
      "estSubscriptionId": 1,
      "isActive": true,
      "name": "TESST APPA Utility",
      "state": "DC",
      "totalCustomers": 22500,
      "totalSubscriptions": 10,
      "milesOfLine": 1200,
      "lineLengthOverhead": 600,
      "lineLengthUnderground": 600,
      "useMeters": true,
      "whenUpdate": "2021-06-29T11:41:45.522312Z",
      "zipCode": "20009"
    }
  }
}

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

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

{
  "data": {
    "type": "Utility",
    "id": "177",
    "attributes": {
      "address": "1875 Connecticut Ave, NW, Suite 1200",
      "aptifyId": 1234,
      "aptifyOrderId": null,
      "averageAnnualHouseholdIncome": "0.00",
      "averageAnnualMegawattHours": "999999.999999999",
      "city": "Washington",
      "estIsActive": true,
      "estSubscriptionId": 1,
      "isActive": true,
      "name": "TESST APPA Utility",
      "state": "DC",
      "totalCustomers": 22500,
      "totalSubscriptions": 10,
      "milesOfLine": 1200,
      "lineLengthOverhead": 600,
      "lineLengthUnderground": 600,
      "useMeters": true,
      "whenUpdate": "2021-06-29T11:41:45.522312Z",
      "zipCode": "20009"
    },
    "relationships": {
      "members": {
        "data": [],
        "meta": {
          "count": 0
        }
      }
    }
  }
}

Status Codes

201 Created – Cause created
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.

Retrieve a Utility ¶

A user must have “leader” authorization to retrieve Utilities.

GET https://reliability.api.publicpower.org/v1/utilities/(int: utility_id)/¶

Example request:

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

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

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

{
  "data": {
    "type": "Utility",
    "id": "177",
    "attributes": {
      "address": "1875 Connecticut Ave, NW, Suite 1200",
      "aptifyId": 1234,
      "aptifyOrderId": null,
      "averageAnnualHouseholdIncome": "0.00",
      "averageAnnualMegawattHours": "999999.999999999",
      "city": "Washington",
      "estIsActive": true,
      "estSubscriptionId": 1,
      "isActive": true,
      "name": "TESST APPA Utility",
      "state": "DC",
      "totalCustomers": 22500,
      "totalSubscriptions": 10,
      "milesOfLine": 1200,
      "lineLengthOverhead": 600,
      "lineLengthUnderground": 600,
      "milesOfLine": 1200,
      "lineLengthOverhead": 600,
      "lineLengthUnderground": 600,
      "useMeters": true,
      "whenUpdate": "2021-06-29T11:41:45.522312Z",
      "zipCode": "20009"
    },
    "relationships": {
      "members": {
        "meta": {
          "count": 2
        },
        "data": [
          {
            "type": "User",
            "id": "2862"
          },
          {
            "type": "User",
            "id": "2861"
          }
        ]
      }
    }
  }
}

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 a Utility ¶

A user must have “admin” authorization to update all Utility attributes. A user authorized as a Utility’s “leader” can update the following attributes:

address
averageAnnualHouseholdIncome
averageAnnualMegawattHours
city
state
totalCustomers
useMeters
zipCode

PATCH https://reliability.api.publicpower.org/v1/utilities/(int: utility_id)/¶

Example request:

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

{
  "data": {
    "id": 177
    "type": "Utility",
    "attributes": {
        "name": "TESST APPA Utility"
    }
  }
}

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

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

{
  "data": {
    "type": "Utility",
    "id": "177",
    "attributes": {
      "address": "1875 Connecticut Ave, NW, Suite 1200",
      "aptifyId": 1234,
      "aptifyOrderId": null,
      "averageAnnualHouseholdIncome": "0.00",
      "averageAnnualMegawattHours": "999999.999999999",
      "city": "Washington",
      "estIsActive": true,
      "estSubscriptionId": 1,
      "isActive": true,
      "name": "TESST APPA Utility",
      "state": "DC",
      "totalCustomers": 22500,
      "totalSubscriptions": 10,
      "useMeters": true,
      "whenUpdate": "2021-06-29T11:41:45.522312Z",
      "zipCode": "20009"
    },
    "relationships": {
      "members": {
        "meta": {
          "count": 1
        },
        "data": [
          {
            "type": "User",
            "id": "2862"
          }
        ]
      }
    }
  }
}

{
  "data": {
    "type": "Utility",
    "id": "177",
    "attributes": {
      "address": "1875 Connecticut Ave, NW, Suite 1200",
      "aptifyId": 1234,
      "aptifyOrderId": null,
      "averageAnnualHouseholdIncome": "0.00",
      "averageAnnualMegawattHours": "999999.999999999",
      "city": "Washington",
      "estIsActive": true,
      "isActive": true,
      "name": "TESST APPA Utility",
      "state": "DC",
      "totalCustomers": 22500,
      "totalSubscriptions": 15,
      "useMeters": true,
      "whenUpdate": "2021-04-27T09:22:51.378979Z",
      "zipCode": "20009"
    },
    "relationships": {
      "members": {
        "meta": {
          "count": 57
        },
        "data": [
          {
            "type": "User",
            "id": "2861"
          },
          {
            "type": "User",
            "id": "5"
          }
        ]
      }
    }
  }
}

Status Codes

200 OK – Utility updated
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.

Delete a Utility ¶

This endpoint was removed because we want to be able to reactivate a utility.