Substations¶

Table of Contents

Resource description
- Attributes
- Relationships
List Substations
Create a Substation
Retrieve a Substation
Update a Substation
Delete a Substation

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

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.
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

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": "Substation",
    "id": "1872",
    "attributes": {
      "name": "New Substation"
    },
    "relationships": {
      "utility": {
        "data": {
          "type": "Utility",
          "id": "66"
        }
      }
    }
  }
}

Status Codes

201 Created – Substation 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 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

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

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

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": "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

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 204 No Content
Content-Type: application/vnd.api+json

Status Codes

204 No Content – Substation deleted
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.