Substations

Resource description

All endpoints adhere to the JSON API specification.

Attributes

Name

Description

Required?

Type

Notes

name

Display name for the Substation

True

string

Relationships

Name

Description

Required?

Type

Notes

utility

Utility this Substation belongs to

True

Foreign key

circuits

Circuits that belong to this Substation

False

Foreign key

Read-only

List Substations

A user must have at least “spectator” authorization to list Substations for their Utility.

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

Example request:

GET /v1/substations/ 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.

  • sort (string) – Comma separated attribute names used to sort list. Available options: name.

Example response:

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

{
  "links": {
    "first": "https://reliability.api.publicpower.dev/v1/substations/?page=1",
    "last": "https://reliability.api.publicpower.dev/v1/substations/?page=2",
    "next": "https://reliability.api.publicpower.dev/v1/substations/?page=2",
    "prev": null
  },
  "data": [
    {
      "type": "Substation",
      "id": "119",
      "attributes": {
        "name": "Glerkins"
      },
      "relationships": {
        "circuits": {
          "data": [
            {
              "type": "Circuit",
              "id": "2064"
            },
            {
              "type": "Circuit",
              "id": "2065"
            },
            {
              "type": "Circuit",
              "id": "2066"
            }
          ],
          "meta": {
            "count": 3
          }
        },
        "utility": {
          "data": {
            "type": "Utility",
            "id": "25"
          }
        }
      }
    },
    {
      "type": "Substation",
      "id": "7",
      "attributes": {
        "name": "Merry Street"
      },
      "relationships": {
        "circuits": {
          "data": [
            {
              "type": "Circuit",
              "id": "13"
            },
            {
              "type": "Circuit",
              "id": "14"
            },
            {
              "type": "Circuit",
              "id": "15"
            }
          ],
          "meta": {
            "count": 3
          }
        },
        "utility": {
          "data": {
            "type": "Utility",
            "id": "7"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pages": 2,
      "count": 17
    }
  }
}
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 Substation

A user must have “leader” authorization to create Substations for their Utility.

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

Example request:

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

{
  "data": {
    "type": "Substation",
    "attributes": {
      "name": "New Substation"
    },
    "relationships": {
      "utility": {
        "data": {
          "type": "Utility",
          "id": "66"
        }
      }
    }
  }
}
Request Headers

Example response:

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

{
  "data": {
    "type": "Substation",
    "id": "1872",
    "attributes": {
      "name": "New Substation"
    },
    "relationships": {
      "utility": {
        "data": {
          "type": "Utility",
          "id": "66"
        }
      }
    }
  }
}
Status Codes

Retrieve a Substation

A user must have at least “spectator” authorization to retrieve Substations for their Utility.

GET https://reliability.api.publicpower.org/v1/substations/(int: substation_id)/

Example request:

GET /v1/substations/1872/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken
Request Headers
Query Parameters
  • include=circuits (string) – Include related Circuit data

Example response:

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

{
  "data": {
    "type": "Substation",
    "id": "119",
    "attributes": {
      "name": "Glerkins"
    },
    "relationships": {
      "circuits": {
        "data": [
          {
            "type": "Circuit",
            "id": "2064"
          },
          {
            "type": "Circuit",
            "id": "2065"
          },
          {
            "type": "Circuit",
            "id": "2066"
          }
        ],
        "meta": {
          "count": 3
        }
      },
      "utility": {
        "data": {
          "type": "Utility",
          "id": "25"
        }
      }
    }
  }
}
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 Substation

A user must have “leader” authorization to update Substations for their Utility.

PATCH https://reliability.api.publicpower.org/v1/substations/(int: substation_id)/

Example request:

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

{
  "data": {
    "id": 66,
    "type": "Substation",
    "attributes": {
      "name": "Modified Substation"
    }
  }
}
Request Headers

Example response:

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

{
  "data": {
    "type": "Substation",
    "id": "1872",
    "attributes": {
      "name": "Modified Substation"
    },
    "relationships": {
      "utility": {
        "data": {
          "type": "Utility",
          "id": "66"
        }
      }
    }
  }
}
Status Codes
  • 200 OK – Substation 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 Substation

A user must have “leader” authorization to delete Substations for their Utility.

DELETE https://reliability.api.publicpower.org/v1/substations/(int: substation_id)/

Example request:

DELETE /v1/substations/66/ 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